Skip to content

Commit 55909c4

Browse files
machowmachow
authored
Merge pull request #273 from machow/docs-render-readme
Docs render readme
2 parents 434e4e7 + 8121952 commit 55909c4

File tree

5 files changed

+222
-84
lines changed

5 files changed

+222
-84
lines changed

‎Makefile‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,17 @@ docs/examples/%: examples/%/_site
3232

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

35+
docs-build-readme: export BUILDING_README = 1
36+
docs-build-readme:
37+
# note that the input file is named GITHUB.qmd, because quart does not
38+
# render files named README.qmd, and it is very cumbersome to work around
39+
# this very strange behavior
40+
cd docs \
41+
&& quarto render GITHUB.qmd \
42+
--to gfm \
43+
--output README.md \
44+
--output-dir ..
45+
3546
docs-build: docs-build-examples
3647
cd docs && quarto add --no-prompt ..
3748
cd docs && quartodoc build

‎README.md‎

Lines changed: 130 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,160 @@
1+
# Overview
12

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

4-
Generate python API documentation for quarto.
8+
Check out the below screencast for a walkthrough of creating a
9+
documentation site, or read on for instructions.
510

6-
## Install
11+
<p align="center">
12+
<a href="https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed">
13+
<img src="https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif" width="75%">
14+
</a>
15+
</p>
716

8-
pip install quartodoc
17+
<br>
918

10-
Or for the latest changes:
19+
## Installation
1120

12-
python3 -m pip install -e git+https://github.com/machow/quartodoc.git#egg=quartodoc
13-
14-
## Basic use
15-
16-
``` python
17-
from quartodoc import get_function, MdRenderer
21+
``` bash
22+
python -m pip install quartodoc
23+
```
1824

19-
# get function object ---
20-
f_obj = get_function("quartodoc", "get_function")
25+
or from GitHub
2126

22-
# render ---
23-
renderer = MdRenderer(header_level = 1)
24-
print(
25-
renderer.to_md(f_obj)
26-
)
27+
``` bash
28+
python -m pip install git+https://github.com/machow/quartodoc.git
2729
```
2830

29-
# get_function
31+
<div>
3032

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

35-
## Parameters
36-
37-
| Name | Type | Description | Default |
38-
|-------------|--------|----------------------------|-----------|
39-
| `module` | str | A module name. | required |
40-
| `func_name` | str | A function name. | required |
41-
| `parser` | str | A docstring parser to use. | `'numpy'` |
41+
## Basic use
4242

43-
## Examples
43+
Getting started with quartodoc takes two steps: configuring quartodoc,
44+
then generating documentation pages for your library.
45+
46+
You can configure quartodoc alongside the rest of your Quarto site in
47+
the
48+
[`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html)
49+
file you are already using for Quarto. To [configure
50+
quartodoc](https://machow.github.io/quartodoc/get-started/basic-docs.html#site-configuration),
51+
you need to add a `quartodoc` section to the top level your
52+
`_quarto.yml` file. Below is a minimal example of a configuration that
53+
documents the `quartodoc` package:
54+
55+
``` yaml
56+
project:
57+
type: website
58+
59+
# tell quarto to read the generated sidebar
60+
metadata-files:
61+
- _sidebar.yml
62+
63+
64+
quartodoc:
65+
# the name used to import the package you want to create reference docs for
66+
package: quartodoc
67+
68+
# write sidebar data to this file
69+
sidebar: _sidebar.yml
70+
71+
sections:
72+
- title: Some functions
73+
desc: Functions to inspect docstrings.
74+
contents:
75+
# the functions being documented in the package.
76+
# you can refer to anything: class methods, modules, etc..
77+
- get_object
78+
- preview
79+
```
4480
45-
```python
46-
>>> get_function("quartodoc", "get_function")
47-
<Function('get_function', ...
48-
```
81+
Now that you have configured quartodoc, you can generate the reference
82+
API docs with the following command:
4983
50-
## How it works
84+
``` bash
85+
quartodoc build
86+
```
5187

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

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

63-
Here is a quick example of how you can grab a function from griffe and
64-
walk through it.
94+
``` bash
95+
quarto preview
96+
```
6597

66-
``` python
67-
from griffe.loader import GriffeLoader
68-
from griffe.docstrings.parsers import Parser
98+
## Rebuilding site
6999

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

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

76-
``` python
77-
f_obj.name
105+
``` bash
106+
quartodoc build --watch
78107
```
79108

80-
'get_function'
109+
Second, preview your site:
81110

82-
``` python
83-
docstring = f_obj.docstring.parsed
84-
docstring
111+
``` bash
112+
quarto preview
85113
```
86114

87-
[<griffe.docstrings.dataclasses.DocstringSectionText at 0x105a2c310>,
88-
<griffe.docstrings.dataclasses.DocstringSectionParameters at 0x10f7961f0>,
89-
<griffe.docstrings.dataclasses.DocstringSectionExamples at 0x10f7965b0>]
90-
91-
Note that quartodoc’s MdRenderer can be called on any part of the parsed
92-
docstring.
93-
94-
``` python
95-
from quartodoc import MdRenderer
96-
97-
renderer = MdRenderer()
98-
99-
print(
100-
renderer.to_md(docstring[1])
101-
)
115+
## Looking up objects
116+
117+
Generating API reference docs for Python objects involves two pieces of
118+
configuration:
119+
120+
1. the package name.
121+
2. a list of objects for content.
122+
123+
quartodoc can look up a wide variety of objects, including functions,
124+
modules, classes, attributes, and methods:
125+
126+
``` yaml
127+
quartodoc:
128+
package: quartodoc
129+
sections:
130+
- title: Some section
131+
desc: ""
132+
contents:
133+
- get_object # function: quartodoc.get_object
134+
- ast.preview # submodule func: quartodoc.ast.preview
135+
- MdRenderer # class: quartodoc.MdRenderer
136+
- MdRenderer.render # method: quartodoc.MDRenderer.render
137+
- renderers # module: quartodoc.renderers
102138
```
103139
104-
| Name | Type | Description | Default |
105-
|-------------|--------|----------------------------|-----------|
106-
| `module` | str | A module name. | required |
107-
| `func_name` | str | A function name. | required |
108-
| `parser` | str | A docstring parser to use. | `'numpy'` |
140+
The functions listed in `contents` are assumed to be imported from the
141+
package.
142+
143+
## Learning more
144+
145+
Go [to the next
146+
page](https://machow.github.io/quartodoc/get-started/basic-docs.html) to
147+
learn how to configure quartodoc sites, or check out these handy pages:
148+
149+
- [Examples
150+
page](https://machow.github.io/quartodoc/examples/index.html): sites
151+
using quartodoc.
152+
- [Tutorials
153+
page](https://machow.github.io/quartodoc/tutorials/index.html):
154+
screencasts of building a quartodoc site.
155+
- [Docstring issues and
156+
examples](https://machow.github.io/quartodoc/get-started/docstring-examples.html):
157+
common issues when formatting docstrings.
158+
- [Programming, the big
159+
picture](https://machow.github.io/quartodoc/get-started/dev-big-picture.html):
160+
the nitty gritty of how quartodoc works, and how to extend it.

‎docs/GITHUB.qmd‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
replace_base_domain: "https://machow.github.io/quartodoc"
3+
replace_rel_path: "/get-started"
4+
filters:
5+
- _filters/replace-readme-links.lua
6+
format: gfm
7+
---
8+
9+
{{< include get-started/overview.qmd >}}

‎docs/_filters/replace-readme-links.lua‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
function Meta(meta)
2+
replace_base_domain = tostring(meta.replace_base_domain[1].text)
3+
replace_rel_path = tostring(meta.replace_rel_path[1].text)
4+
end
5+
6+
-- pandoc Link object: replace the .qmd in the target with .html
7+
function Link(link)
8+
-- replace .qmd with .html in target
9+
-- replace beginning with replace_base_domain, accounting for / and ./ in paths
10+
-- e.g. ./overview.qmd -> {replace_rel_path}/get-started/overview.html
11+
-- e.g. /index.qmd -> {replace_base_domain}/index.html
12+
-- e.g. https://example.com -> https://example.com
13+
if link.target:match("%.qmd$") or link.target:match("%.qmd#.*$") then
14+
link.target = link.target:gsub("%.qmd", ".html")
15+
if link.target:match("^%./") then
16+
link.target = link.target:gsub("^%./", replace_base_domain .. replace_rel_path .. "/")
17+
end
18+
if link.target:match("^/") then
19+
link.target = link.target:gsub("^/", replace_base_domain .. "/")
20+
end
21+
-- if target does not start with http, do same as above
22+
if not link.target:match("^http") then
23+
link.target = replace_base_domain .. replace_rel_path .. "/" .. link.target
24+
end
25+
end
26+
27+
return link
28+
end
29+
30+
return {
31+
{
32+
Meta = Meta
33+
},
34+
{
35+
Link = Link
36+
}
37+
}

‎docs/get-started/overview.qmd‎

Lines changed: 35 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,39 @@ jupyter:
1313
**quartodoc** lets you quickly generate Python package API reference documentation using Markdown and [Quarto](https://quarto.org).
1414
quartodoc is designed as an alternative to [Sphinx](https://www.sphinx-doc.org/en/master/).
1515

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

19+
20+
```{python}
21+
#| echo: false
22+
#| output: asis
23+
24+
# this code ensures that the proper html for the tutorial screencast is used,
25+
# depending on whether it's being rendered for the github README, or doc site.
26+
import os
27+
28+
if "BUILDING_README" in os.environ:
29+
# I don't know why, but we need to repeat the Installation header here.
30+
# or quarto makes it disappear when we generate the readme
31+
print("""
32+
<p align="center">
33+
<a href="https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed">
34+
<img src="https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif" width="75%">
35+
</a>
36+
</p>
37+
38+
<br>
39+
40+
## Installation
41+
""")
42+
else:
43+
print("""
1844
<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>
45+
<br>
46+
""")
1947
48+
```
2049

2150
## Installation
2251

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

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

44-
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:
73+
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:
4574

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

129158
## Learning more
130159

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

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

0 commit comments

Comments
 (0)