<liclass="toctree-l1 current has-children"><aclass="reference internal"href="index.html">Documentation</a><inputchecked=""class="toctree-checkbox"id="toctree-checkbox-6"name="toctree-checkbox-6"role="switch"type="checkbox"/><labelfor="toctree-checkbox-6"><divclass="visually-hidden">Toggle navigation of Documentation</div><iclass="icon"><svg><usehref="#svg-arrow-right"></use></svg></i></label><ulclass="current">
<p>The primary driver of this package’s documentation is Sphinx’s <codeclass="docutils literal notranslate"><spanclass="pre">autodoc</span></code> extension,
using the <aclass="reference external"href="https://pradyunsg.me/furo/">Furo theme</a>.</p>
<p><strong>High-level details</strong>:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">sphinx-apidoc</span></code> generates package-based documentation to the <codeclass="docutils literal notranslate"><spanclass="pre">_autoref/</span></code> directory,
with navigation available under “Autoref” in the sidebar.</p></li>
<li><p>Markdown-based documentation files are manually written under the <codeclass="docutils literal notranslate"><spanclass="pre">reference/</span></code>
directory, showing up under “Contents” in the sidebar.</p></li>
<p>All files are placed under <codeclass="docutils literal notranslate"><spanclass="pre">docs/sphinx</span></code>:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">_</span></code>-prefixed are Sphinx-managed directories</p>
<ul>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">_build/html/</span></code> houses output HTML files</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">_autoref/</span></code> is the target for module-based RST files written by <codeclass="docutils literal notranslate"><spanclass="pre">autodoc</span></code></p></li>
</ul>
</li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">reference/</span></code>: houses all manually written documentation (totally separate from
auto-generated package docs)</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">conf.py</span></code>: single Sphinx configuration file</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">index.md</span></code>: documentation index, setups up a persistent sidebar across all other pages</p></li>
</ul>
<p>For manually written documentation under <codeclass="docutils literal notranslate"><spanclass="pre">reference/</span></code>, topics are nested as needed. Within
a nested directory <codeclass="docutils literal notranslate"><spanclass="pre">reference/<topic></span></code>, an <codeclass="docutils literal notranslate"><spanclass="pre">index.md</span></code> should created with content like:</p>
<p>Sphinx’s <codeclass="docutils literal notranslate"><spanclass="pre">autodoc</span></code> extension allows automatic generation of documents according to
(Python) subpackage structure and available docstrings. A few notes here:</p>
<ul>
<li><p>In the <codeclass="docutils literal notranslate"><spanclass="pre">conf.py</span></code> file, autodoc is enabled by adding <codeclass="docutils literal notranslate"><spanclass="pre">"sphinx.ext.autodoc"</span></code> to
the extensions list. <codeclass="docutils literal notranslate"><spanclass="pre">"sphinx.ext.viewcode"</span></code> can also be added to provide
links to source code.</p></li>
<li><p>Documents are actually generated by calling the <codeclass="docutils literal notranslate"><spanclass="pre">sphinx-apidoc</span></code> CLI command. The
<p>This writes the automatically generated docs for modules in the package at the
local directory <codeclass="docutils literal notranslate"><spanclass="pre">localsys/</span></code> to the <codeclass="docutils literal notranslate"><spanclass="pre">docs/sphinx/_autoref</span></code> directory. These are
reStructuredText files by default.</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">--module-first</span></code> 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.</p></li>
<li><p>See available <codeclass="docutils literal notranslate"><spanclass="pre">sphinx-apidoc</span></code> options <aclass="reference external"href="https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html">here</a>, as well as more advanced config
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">myst_parser</span></code> 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:</p>
<p><strong>Page hierarchies</strong>: the following will generate link hierarchy according to the provided
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">:maxdepth:</span></code> limits the depth of nesting</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">:caption:</span></code> title for the group of pages</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">:hidden:</span></code> if provided, links will only show in the sidebar (hidden on the page)</p></li>
<li><p>Constituent files: listed files will be rendered as a link directly. If a listed file
has a <codeclass="docutils literal notranslate"><spanclass="pre">{toctree}</span></code> 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.</p></li>
</ul>
<p><strong>Include files</strong>: the following will include file content
