Skip to content

Commit

Permalink
Merge pull request #273 from machow/docs-render-readme
Browse files Browse the repository at this point in the history 
Docs render readme
  • Loading branch information
@machow
machow authored Sep 18, 2023
2 parents 434e4e7 + 8121952 commit 55909c4
Show file tree
Hide file tree
Showing 5 changed files with 222 additions and 84 deletions.
11 changes: 11 additions & 0 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,17 @@ docs/examples/%: examples/%/_site

docs-build-examples: docs/examples/single-page docs/examples/pkgdown docs/examples/auto-package

docs-build-readme: export BUILDING_README = 1
docs-build-readme:
# note that the input file is named GITHUB.qmd, because quart does not
# render files named README.qmd, and it is very cumbersome to work around
# this very strange behavior
cd docs \
&& quarto render GITHUB.qmd \
--to gfm \
--output README.md \
--output-dir ..

docs-build: docs-build-examples
cd docs && quarto add --no-prompt ..
cd docs && quartodoc build
Expand Down
208 changes: 130 additions & 78 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,108 +1,160 @@
# Overview

# quartodoc
**quartodoc** lets you quickly generate Python package API reference
documentation using Markdown and [Quarto](https://quarto.org). quartodoc
is designed as an alternative to
[Sphinx](https://www.sphinx-doc.org/en/master/).

Generate python API documentation for quarto.
Check out the below screencast for a walkthrough of creating a
documentation site, or read on for instructions.

## Install
<p align="center">
<a href="https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed">
<img src="https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif" width="75%">
</a>
</p>

pip install quartodoc
<br>

Or for the latest changes:
## Installation

python3 -m pip install -e git+https://github.com/machow/quartodoc.git#egg=quartodoc

## Basic use

``` python
from quartodoc import get_function, MdRenderer
``` bash
python -m pip install quartodoc
```

# get function object ---
f_obj = get_function("quartodoc", "get_function")
or from GitHub

# render ---
renderer = MdRenderer(header_level = 1)
print(
renderer.to_md(f_obj)
)
``` bash
python -m pip install git+https://github.com/machow/quartodoc.git
```

# get_function
<div>

`get_function(module: str, func_name: str, parser: str = 'numpy')`
> **Install Quarto**
>
> If you haven’t already, you’ll need to [install
> Quarto](https://quarto.org/docs/get-started/) before you can use
> quartodoc.
Fetch a function.
</div>

## Parameters

| Name | Type | Description | Default |
|-------------|--------|----------------------------|-----------|
| `module` | str | A module name. | required |
| `func_name` | str | A function name. | required |
| `parser` | str | A docstring parser to use. | `'numpy'` |
## Basic use

## Examples
Getting started with quartodoc takes two steps: configuring quartodoc,
then generating documentation pages for your library.

You can configure quartodoc alongside the rest of your Quarto site in
the
[`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html)
file you are already using for Quarto. To [configure
quartodoc](https://machow.github.io/quartodoc/get-started/basic-docs.html#site-configuration),
you need to add a `quartodoc` section to the top level your
`_quarto.yml` file. Below is a minimal example of a configuration that
documents the `quartodoc` package:

``` yaml
project:
type: website

# tell quarto to read the generated sidebar
metadata-files:
- _sidebar.yml


quartodoc:
# the name used to import the package you want to create reference docs for
package: quartodoc

# write sidebar data to this file
sidebar: _sidebar.yml

sections:
- title: Some functions
desc: Functions to inspect docstrings.
contents:
# the functions being documented in the package.
# you can refer to anything: class methods, modules, etc..
- get_object
- preview
```
```python
>>> get_function("quartodoc", "get_function")
<Function('get_function', ...
```
Now that you have configured quartodoc, you can generate the reference
API docs with the following command:
## How it works
``` bash
quartodoc build
```

quartodoc consists of two pieces:
This will create a `reference/` directory with an `index.qmd` and
documentation pages for listed functions, like `get_object` and
`preview`.

- **collection**: using the library
[griffe](https://github.com/mkdocstrings/griffe) to statically collect
information about functions and classes in a program.
- **docstring parsing**: also handled by griffe, which breaks it into a
tree structure.
- **docstring rendering**: use plum-dispatch on methods like
MdRenderer.to_md to decide how to visit and render each piece of the
tree (e.g. the examples section, a parameter, etc..).
Finally, preview your website with quarto:

Here is a quick example of how you can grab a function from griffe and
walk through it.
``` bash
quarto preview
```

``` python
from griffe.loader import GriffeLoader
from griffe.docstrings.parsers import Parser
## Rebuilding site

griffe = GriffeLoader(docstring_parser = Parser("numpy"))
mod = griffe.load_module("quartodoc")
You can preview your `quartodoc` site using the following commands:

f_obj = mod._modules_collection["quartodoc.get_function"]
```
First, watch for changes to the library you are documenting so that your
docs will automatically re-generate:

``` python
f_obj.name
``` bash
quartodoc build --watch
```

'get_function'
Second, preview your site:

``` python
docstring = f_obj.docstring.parsed
docstring
``` bash
quarto preview
```

[<griffe.docstrings.dataclasses.DocstringSectionText at 0x105a2c310>,
<griffe.docstrings.dataclasses.DocstringSectionParameters at 0x10f7961f0>,
<griffe.docstrings.dataclasses.DocstringSectionExamples at 0x10f7965b0>]

Note that quartodoc’s MdRenderer can be called on any part of the parsed
docstring.

``` python
from quartodoc import MdRenderer

renderer = MdRenderer()

print(
renderer.to_md(docstring[1])
)
## Looking up objects

Generating API reference docs for Python objects involves two pieces of
configuration:

1. the package name.
2. a list of objects for content.

quartodoc can look up a wide variety of objects, including functions,
modules, classes, attributes, and methods:

``` yaml
quartodoc:
package: quartodoc
sections:
- title: Some section
desc: ""
contents:
- get_object # function: quartodoc.get_object
- ast.preview # submodule func: quartodoc.ast.preview
- MdRenderer # class: quartodoc.MdRenderer
- MdRenderer.render # method: quartodoc.MDRenderer.render
- renderers # module: quartodoc.renderers
```
| Name | Type | Description | Default |
|-------------|--------|----------------------------|-----------|
| `module` | str | A module name. | required |
| `func_name` | str | A function name. | required |
| `parser` | str | A docstring parser to use. | `'numpy'` |
The functions listed in `contents` are assumed to be imported from the
package.

## Learning more

Go [to the next
page](https://machow.github.io/quartodoc/get-started/basic-docs.html) to
learn how to configure quartodoc sites, or check out these handy pages:

- [Examples
page](https://machow.github.io/quartodoc/examples/index.html): sites
using quartodoc.
- [Tutorials
page](https://machow.github.io/quartodoc/tutorials/index.html):
screencasts of building a quartodoc site.
- [Docstring issues and
examples](https://machow.github.io/quartodoc/get-started/docstring-examples.html):
common issues when formatting docstrings.
- [Programming, the big
picture](https://machow.github.io/quartodoc/get-started/dev-big-picture.html):
the nitty gritty of how quartodoc works, and how to extend it.
9 changes: 9 additions & 0 deletions docs/GITHUB.qmd
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
replace_base_domain: "https://machow.github.io/quartodoc"
replace_rel_path: "/get-started"
filters:
- _filters/replace-readme-links.lua
format: gfm
---

{{< include get-started/overview.qmd >}}
37 changes: 37 additions & 0 deletions docs/_filters/replace-readme-links.lua
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
function Meta(meta)
replace_base_domain = tostring(meta.replace_base_domain[1].text)
replace_rel_path = tostring(meta.replace_rel_path[1].text)
end

-- pandoc Link object: replace the .qmd in the target with .html
function Link(link)
-- replace .qmd with .html in target
-- replace beginning with replace_base_domain, accounting for / and ./ in paths
-- e.g. ./overview.qmd -> {replace_rel_path}/get-started/overview.html
-- e.g. /index.qmd -> {replace_base_domain}/index.html
-- e.g. https://example.com -> https://example.com
if link.target:match("%.qmd$") or link.target:match("%.qmd#.*$") then
link.target = link.target:gsub("%.qmd", ".html")
if link.target:match("^%./") then
link.target = link.target:gsub("^%./", replace_base_domain .. replace_rel_path .. "/")
end
if link.target:match("^/") then
link.target = link.target:gsub("^/", replace_base_domain .. "/")
end
-- if target does not start with http, do same as above
if not link.target:match("^http") then
link.target = replace_base_domain .. replace_rel_path .. "/" .. link.target
end
end

return link
end

return {
{
Meta = Meta
},
{
Link = Link
}
}
41 changes: 35 additions & 6 deletions docs/get-started/overview.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,39 @@ jupyter:
**quartodoc** lets you quickly generate Python package API reference documentation using Markdown and [Quarto](https://quarto.org).
quartodoc is designed as an alternative to [Sphinx](https://www.sphinx-doc.org/en/master/).


Check out the below screencast for a walkthrough of creating a documentation site, or read on for instructions.


```{python}
#| echo: false
#| output: asis
# this code ensures that the proper html for the tutorial screencast is used,
# depending on whether it's being rendered for the github README, or doc site.
import os
if "BUILDING_README" in os.environ:
# I don't know why, but we need to repeat the Installation header here.
# or quarto makes it disappear when we generate the readme
print("""
<p align="center">
<a href="https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed">
<img src="https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif" width="75%">
</a>
</p>
<br>
## Installation
""")
else:
print("""
<div style="position: relative; padding-bottom: 64.5933014354067%; height: 0;"><iframe src="https://www.loom.com/embed/fb4eb736848e470b8409ba46b514e2ed?sid=31db7652-43c6-4474-bab3-19dea2170775" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
<br>
""")
```

## Installation

Expand All @@ -41,7 +70,7 @@ If you haven't already, you'll need to [install Quarto](https://quarto.org/docs/

Getting started with quartodoc takes two steps: configuring quartodoc, then generating documentation pages for your library.

You can configure quartodoc alongside the rest of your Quarto site in the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html) file you are already using for Quarto. To [configure quartodoc](basic-docs.qmd#site-configuration), you need to add a `quartodoc` section to the top level your `_quarto.yml` file. Below is a minimal example of a configuration that documents the `quartodoc` package:
You can configure quartodoc alongside the rest of your Quarto site in the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html) file you are already using for Quarto. To [configure quartodoc](./basic-docs.qmd#site-configuration), you need to add a `quartodoc` section to the top level your `_quarto.yml` file. Below is a minimal example of a configuration that documents the `quartodoc` package:

```yaml
project:
Expand Down Expand Up @@ -128,9 +157,9 @@ The functions listed in `contents` are assumed to be imported from the package.

## Learning more

Go [to the next page](./get-started/basic-docs.qmd) to learn how to configure quartodoc sites, or check out these handy pages:
Go [to the next page](basic-docs.qmd) to learn how to configure quartodoc sites, or check out these handy pages:

* [Examples page](./examples/index.qmd): sites using quartodoc.
* [Tutorials page](./tutorials/index.qmd): screencasts of building a quartodoc site.
* [Docstring issues and examples](./get-started/docstring-examples.qmd): common issues when formatting docstrings.
* [Programming, the big picture](./get-started/dev-big-picture.qmd): the nitty gritty of how quartodoc works, and how to extend it.
* [Examples page](/examples/index.qmd): sites using quartodoc.
* [Tutorials page](/tutorials/index.qmd): screencasts of building a quartodoc site.
* [Docstring issues and examples](./docstring-examples.qmd): common issues when formatting docstrings.
* [Programming, the big picture](./dev-big-picture.qmd): the nitty gritty of how quartodoc works, and how to extend it.

0 comments on commit 55909c4

Please sign in to comment.