The primary driver of this package's documentation is Sphinx's `autodoc` extension,
using the [Furo theme][1].

`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.

Markdown-based documentation files are manually written under the 

`_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)

: houses all manually written documentation (totally separate from

`index.md`: documentation index, setups up a persistent sidebar across all other pages

: 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's `autodoc` extension allows automatic generation of documents according to
(Python) subpackage structure and available docstrings. A few notes here:

 extension allows automatic generation of documents according to

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:

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.

 places the module-level descriptions at the top of the module page.

See available `sphinx-apidoc` options [here][2], as well as more advanced config
[here][3].

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:

 extension enables Markdown (or something close to it) to be used when

**Page hierarchies**: the following will generate link hierarchy according to the provided
pages:

: the following will generate link hierarchy according to the provided

:maxdepth: <n>
:caption: <caption>
:hidden:

example-file-1
example-file-2
example-dir/index
...
\`\`\`

`:hidden:` if provided, links will only show in the sidebar (hidden on the page)

 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.

 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

**Include files**: the following will include file content
pages: