147 lines
4.9 KiB
Markdown
147 lines
4.9 KiB
Markdown
# Sphinx
|
|
The primary driver of this package's documentation is Sphinx's `autodoc` extension,
|
|
using the [Furo theme][1].
|
|
|
|
**High-level details**:
|
|
|
|
- `sphinx-apidoc` generates package-based documentation to the `_autoref/` directory,
|
|
with navigation available under "Autoref" in the sidebar.
|
|
- Markdown-based documentation files are manually written under the `reference/`
|
|
directory, showing up under "Contents" in the sidebar.
|
|
|
|
## Detailed directory structure
|
|
All files are placed under `docs/sphinx`:
|
|
|
|
- `_`-prefixed are Sphinx-managed directories
|
|
* `_build/html/` houses output HTML files
|
|
* `_autoref/` is the target for module-based RST files written by `autodoc`
|
|
- `reference/`: houses all manually written documentation (totally separate from
|
|
auto-generated package docs)
|
|
- `conf.py`: single Sphinx configuration file
|
|
- `index.md`: documentation index, setups up a persistent sidebar across all other pages
|
|
|
|
For manually written documentation under `reference/`, topics are nested as needed. Within
|
|
a nested directory `reference/<topic>`, an `index.md` should created with content like:
|
|
|
|
```
|
|
# <Topic>
|
|
|
|
\`\`\`{toctree}
|
|
:hidden:
|
|
|
|
sub-topic-1.rst
|
|
sub-topic-2.rst
|
|
...
|
|
\`\`\`
|
|
```
|
|
|
|
This will add the nested directory to the sidebar navigation, using the name set under the
|
|
top-level header. See [Markdown syntax][#markdown-syntax] for more details on the syntax.
|
|
|
|
## Sphinx autodoc
|
|
Sphinx's `autodoc` extension allows automatic generation of documents according to
|
|
(Python) subpackage structure and available docstrings. A few notes here:
|
|
|
|
- In the `conf.py` file, autodoc is enabled by adding `"sphinx.ext.autodoc"` to
|
|
the extensions list. `"sphinx.ext.viewcode"` can also be added to provide
|
|
links to source code.
|
|
- Documents are actually generated by calling the `sphinx-apidoc` CLI command. The
|
|
current Makefile uses the following call:
|
|
|
|
```sh
|
|
sphinx-apidoc --module-first -o docs/sphinx/_autoref/ localsys
|
|
```
|
|
|
|
This writes the automatically generated docs for modules in the package at the
|
|
local directory `localsys/` to the `docs/sphinx/_autoref` directory. These are
|
|
reStructuredText files by default.
|
|
* `--module-first` places the module-level descriptions at the top of the module page.
|
|
By default, this is placed at the bottom (oddly), and can be obscured by large lists
|
|
of subpackages if this flag isn't provided.
|
|
* See available `sphinx-apidoc` options [here][2], as well as more advanced config
|
|
[here][3].
|
|
|
|
|
|
## Markdown syntax
|
|
The `myst_parser` extension enables Markdown (or something close to it) to be used when
|
|
writing documentation files. The Sphinx directives can be difficult to track, and
|
|
they change slightly under the MyST Markdown syntax. The following are a few common
|
|
blocks:
|
|
|
|
**Page hierarchies**: the following will generate link hierarchy according to the provided
|
|
pages:
|
|
|
|
```
|
|
\`\`\`{toctree}
|
|
:maxdepth: <n>
|
|
:caption: <caption>
|
|
:hidden:
|
|
|
|
example-file-1
|
|
example-file-2
|
|
example-dir/index
|
|
...
|
|
\`\`\`
|
|
```
|
|
|
|
- `:maxdepth:` limits the depth of nesting
|
|
- `:caption:` title for the group of pages
|
|
- `:hidden:` if provided, links will only show in the sidebar (hidden on the page)
|
|
- Constituent files: listed files will be rendered as a link directly. If a listed file
|
|
has a `{toctree}` directive, this tree will be rendered in place of the page's link as a
|
|
dropdown. The dropdown will be named according to the file's top-level heading, and
|
|
clicking directly on the dropdown header will show that page's content. Files found in
|
|
the tree will be placed as links under the dropdown, recursively subject to same rules
|
|
described here.
|
|
|
|
**Include files**: the following will include file content
|
|
pages:
|
|
|
|
```
|
|
\`\`\`{include} README.md
|
|
\`\`\`
|
|
```
|
|
|
|
**Reference directives**
|
|
|
|
|
|
## Notes on docstring syntax
|
|
- Code literals need to be surrounded in two backticks, e.g., "``variable``". Sphinx will
|
|
also complain if you make the reference plural by having an "s" after the backtick; it
|
|
needs to go on the inside.
|
|
- MyST parsing, even if enabled, doesn't apply to docstrings. You need to use RST
|
|
generally, with a few directives being different under extensions like `napoleon`.
|
|
- Code blocks and admonitions need a space between the heading and the rest of the
|
|
content.
|
|
|
|
Nice syntax cheatsheet [here][4]
|
|
|
|
General docstring structure should be structured as follows:
|
|
|
|
```python
|
|
def example_function(a, b):
|
|
'''
|
|
Minimal function description. (either first sentence or line; gets used in
|
|
autosummaries)
|
|
|
|
Additional exposition, unwrapped by admonitions.
|
|
|
|
.. admonition:: Admonition description
|
|
Indented content, code blocks, lists, etc
|
|
|
|
Parameters:
|
|
a: a's description
|
|
b: b's description
|
|
|
|
Returns:
|
|
<return-type>: Description of return value
|
|
'''
|
|
...
|
|
```
|
|
|
|
|
|
[1]: https://pradyunsg.me/furo/
|
|
[2]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html
|
|
[3]: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#
|
|
[4]: https://sphinx-tutorial.readthedocs.io/cheatsheet/
|