Skip to content

Commit 8b0e8be

Browse files
machowmachow
committed
docs: add gh readme renderered from docs home page
1 parent 7339f4d commit 8b0e8be

File tree

1 file changed

+105
-70
lines changed

1 file changed

+105
-70
lines changed

‎README.md‎

Lines changed: 105 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,143 @@
1+
# Overview
12

2-
# quartodoc
3+
quartodoc lets you quickly generate python package documentation, using
4+
markdown and [quarto](https://quarto.org). It is designed as an
5+
alternative to Sphinx.
36

4-
Generate python API documentation for quarto.
7+
Check out the screencast below for a full walkthrough of creating a
8+
documentation site, or read on for instructions on installation and use.
59

6-
## Install
10+
<br>
711

8-
pip install quartodoc
12+
<div style="position: relative; padding-bottom: 64.5933014354067%; height: 0;">
913

10-
Or for the latest changes:
14+
<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%;">
15+
</iframe>
1116

12-
python3 -m pip install -e git+https://github.com/machow/quartodoc.git#egg=quartodoc
17+
</div>
1318

14-
## Basic use
19+
<br> <br>
1520

16-
``` python
17-
from quartodoc import get_function, MdRenderer
21+
## Installation
1822

19-
# get function object ---
20-
f_obj = get_function("quartodoc", "get_function")
23+
``` bash
24+
python -m pip install quartodoc
2125

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

29-
# get_function
30+
<div>
3031

31-
`get_function(module: str, func_name: str, parser: str = 'numpy')`
32+
> **Note**
33+
>
34+
> In order to install quarto, see the quarto [get started
35+
> page](https://quarto.org/docs/get-started/).
3236
33-
Fetch a function.
37+
</div>
3438

35-
## Parameters
39+
## Basic use
3640

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+
Getting started with quartodoc takes two steps: configuring a quarto
42+
website, and generating documentation pages for your library.
4243

43-
## Examples
44+
First, create a `_quarto.yml` file with the following:
4445

45-
```python
46-
>>> get_function("quartodoc", "get_function")
47-
<Function('get_function', ...
48-
```
46+
``` yaml
47+
project:
48+
type: website
4949

50-
## How it works
50+
# tell quarto to read the generated sidebar
51+
metadata-files:
52+
- _sidebar.yml
5153

52-
quartodoc consists of two pieces:
5354

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..).
55+
quartodoc:
56+
# the name used to import the package
57+
package: quartodoc
6258

63-
Here is a quick example of how you can grab a function from griffe and
64-
walk through it.
59+
# write sidebar data to this file
60+
sidebar: _sidebar.yml
6561

66-
``` python
67-
from griffe.loader import GriffeLoader
68-
from griffe.docstrings.parsers import Parser
62+
sections:
63+
- title: Some functions
64+
desc: Functions to inspect docstrings.
65+
contents:
66+
# the functions being documented in the package.
67+
# you can refer to anything: class methods, modules, etc..
68+
- get_object
69+
- preview
70+
```
6971
70-
griffe = GriffeLoader(docstring_parser = Parser("numpy"))
71-
mod = griffe.load_module("quartodoc")
72+
Next, run this command to generate your API pages:
7273
73-
f_obj = mod._modules_collection["quartodoc.get_function"]
74+
``` bash
75+
quartodoc build
7476
```
7577

76-
``` python
77-
f_obj.name
78+
This should create a `reference/` directory with an `index.qmd` and
79+
documentation pages for listed functions, like `get_object` and
80+
`preview`.
81+
82+
Finally, preview your website with quarto:
83+
84+
``` bash
85+
quarto preview
7886
```
7987

80-
'get_function'
88+
## Rebuilding site
89+
90+
You can preview your `quartodoc` site using the following commands:
91+
92+
First, watch for changes to the library you are documenting so that your
93+
docs will automatically re-generate:
8194

82-
``` python
83-
docstring = f_obj.docstring.parsed
84-
docstring
95+
``` bash
96+
quartodoc build --watch
8597
```
8698

87-
[<griffe.docstrings.dataclasses.DocstringSectionText at 0x105a2c310>,
88-
<griffe.docstrings.dataclasses.DocstringSectionParameters at 0x10f7961f0>,
89-
<griffe.docstrings.dataclasses.DocstringSectionExamples at 0x10f7965b0>]
99+
Second, preview your site:
90100

91-
Note that quartodoc’s MdRenderer can be called on any part of the parsed
92-
docstring.
101+
``` bash
102+
quarto preview
103+
```
104+
105+
## Looking up objects
106+
107+
Finding python objects to document involves two pieces of configuration:
93108

94-
``` python
95-
from quartodoc import MdRenderer
109+
- the package name.
110+
- a list of objects for content.
96111

97-
renderer = MdRenderer()
112+
Note that quartodoc can look up anything—whether functions, modules,
113+
classes, attributes, or methods.
98114

99-
print(
100-
renderer.to_md(docstring[1])
101-
)
115+
``` yaml
116+
quartodoc:
117+
package: quartodoc
118+
sections:
119+
- title: Some section
120+
desc: ""
121+
contents:
122+
- get_object # function: quartodoc.get_object
123+
- ast.preview # submodule func: quartodoc.ast.preview
124+
- MdRenderer # class: quartodoc.MdRenderer
125+
- MdRenderer.render # method: quartodoc.MDRenderer.render
126+
- renderers # module: quartodoc.renderers
102127
```
103128
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'` |
129+
The functions listed in `contents` are assumed to be imported from the
130+
package.
131+
132+
## Learning more
133+
134+
Go [to the next page](./get-started/basic-docs.qmd) to learn how to
135+
configure quartodoc sites, or check out these handy pages:
136+
137+
- [Examples page](./examples/index.qmd): sites using quartodoc.
138+
- [Tutorials page](./tutorials/index.qmd): screencasts of building a
139+
quartodoc site.
140+
- [Docstring issues and examples](./get-started/docstring-examples.qmd):
141+
common issues when formatting docstrings.
142+
- [Programming, the big picture](./get-started/dev-big-picture.qmd): the
143+
nitty gritty of how quartodoc works, and how to extend it.

0 commit comments

Comments
 (0)