olog/co3
1
0
Fork 0
Code Issues 2 Pull Requests Packages Projects Releases Wiki Activity
9badda5446
co3/docs/_build/html/reference/documentation/sphinx.html

384 lines
19 KiB
HTML
Raw Normal View History

initial commit
2024-03-29 06:11:30 +00:00
<!doctype html>
<html class="no-js" lang="en" data-content_root="../../">
<head><meta charset="utf-8"/>
<meta name="viewport" content="width=device-width,initial-scale=1"/>
<meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" /><link rel="prev" title="Documentation" href="index.html" />
<!-- Generated with Sphinx 7.2.6 and Furo 2024.01.29 -->
<title>Sphinx - co4 documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=a746c00c" />
<link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?v=135e06be" />
<link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?v=36a5483c" />
<style>
body {
--color-code-background: #f8f8f8;
--color-code-foreground: black;
}
@media not print {
body[data-theme="dark"] {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
@media (prefers-color-scheme: dark) {
body:not([data-theme="light"]) {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
}
}
</style></head>
<body>
<script>
document.body.dataset.theme = localStorage.getItem("theme") || "auto";
</script>
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-toc" viewBox="0 0 24 24">
<title>Contents</title>
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
<path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
</svg>
</symbol>
<symbol id="svg-menu" viewBox="0 0 24 24">
<title>Menu</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
<line x1="3" y1="12" x2="21" y2="12"></line>
<line x1="3" y1="6" x2="21" y2="6"></line>
<line x1="3" y1="18" x2="21" y2="18"></line>
</svg>
</symbol>
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
<title>Expand</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
<polyline points="9 18 15 12 9 6"></polyline>
</svg>
</symbol>
<symbol id="svg-sun" viewBox="0 0 24 24">
<title>Light mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
<circle cx="12" cy="12" r="5"></circle>
<line x1="12" y1="1" x2="12" y2="3"></line>
<line x1="12" y1="21" x2="12" y2="23"></line>
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
<line x1="1" y1="12" x2="3" y2="12"></line>
<line x1="21" y1="12" x2="23" y2="12"></line>
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
</svg>
</symbol>
<symbol id="svg-moon" viewBox="0 0 24 24">
<title>Dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
</svg>
</symbol>
<symbol id="svg-sun-half" viewBox="0 0 24 24">
<title>Auto light/dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
<circle cx="12" cy="12" r="9" />
<path d="M13 12h5" />
<path d="M13 15h4" />
<path d="M13 18h1" />
<path d="M13 9h4" />
<path d="M13 6h1" />
</svg>
</symbol>
</svg>
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
<label class="overlay sidebar-overlay" for="__navigation">
<div class="visually-hidden">Hide navigation sidebar</div>
</label>
<label class="overlay toc-overlay" for="__toc">
<div class="visually-hidden">Hide table of contents sidebar</div>
</label>
<div class="page">
<header class="mobile-header">
<div class="header-left">
<label class="nav-overlay-icon" for="__navigation">
<div class="visually-hidden">Toggle site navigation sidebar</div>
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
</label>
</div>
<div class="header-center">
<a href="../../index.html"><div class="brand">co4 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
<button class="theme-toggle">
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
<svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-header-icon" for="__toc">
<div class="visually-hidden">Toggle table of contents sidebar</div>
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
</header>
<aside class="sidebar-drawer">
<div class="sidebar-container">
<div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
<span class="sidebar-brand-text">co4 documentation</span>
</a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
<input type="hidden" name="check_keywords" value="yes">
<input type="hidden" name="area" value="default">
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<p class="caption" role="heading"><span class="caption-text">Autoref</span></p>
<ul>
<li class="toctree-l1 has-children"><a class="reference internal" href="../../_autoref/co4.html">co4 package</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of co4 package</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="../../_autoref/co4.accessors.html">co4.accessors package</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../_autoref/co4.collectors.html">co4.collectors package</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../_autoref/co4.composers.html">co4.composers package</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../_autoref/co4.databases.html">co4.databases package</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../_autoref/co4.managers.html">co4.managers package</a></li>
</ul>
</li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1 current has-children"><a class="reference internal" href="index.html">Documentation</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Documentation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current">
<li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Sphinx</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
</aside>
<div class="main">
<div class="content">
<div class="article-container">
<a href="#" class="back-to-top muted-link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
</svg>
<span>Back to top</span>
</a>
<div class="content-icon-container">
<div class="theme-toggle-container theme-toggle-content">
<button class="theme-toggle">
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
<svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-content-icon" for="__toc">
<div class="visually-hidden">Toggle table of contents sidebar</div>
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
<article role="main">
<section id="sphinx">
<h1>Sphinx<a class="headerlink" href="#sphinx" title="Link to this heading">#</a></h1>
<p>The primary driver of this package’s documentation is Sphinx’s <code class="docutils literal notranslate"><span class="pre">autodoc</span></code> extension,
using the <a class="reference external" href="https://pradyunsg.me/furo/">Furo theme</a>.</p>
<p><strong>High-level details</strong>:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">sphinx-apidoc</span></code> generates package-based documentation to the <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">reference/</span></code>
directory, showing up under “Contents” in the sidebar.</p></li>
</ul>
<section id="detailed-directory-structure">
<h2>Detailed directory structure<a class="headerlink" href="#detailed-directory-structure" title="Link to this heading">#</a></h2>
<p>All files are placed under <code class="docutils literal notranslate"><span class="pre">docs/sphinx</span></code>:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">_</span></code>-prefixed are Sphinx-managed directories</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">_build/html/</span></code> houses output HTML files</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">_autoref/</span></code> is the target for module-based RST files written by <code class="docutils literal notranslate"><span class="pre">autodoc</span></code></p></li>
</ul>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">reference/</span></code>: houses all manually written documentation (totally separate from
auto-generated package docs)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">conf.py</span></code>: single Sphinx configuration file</p></li>
<li><p><code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">reference/</span></code>, topics are nested as needed. Within
a nested directory <code class="docutils literal notranslate"><span class="pre">reference/&lt;topic&gt;</span></code>, an <code class="docutils literal notranslate"><span class="pre">index.md</span></code> should created with content like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span># &lt;Topic&gt;
\`\`\`{toctree}
:hidden:
sub-topic-1.rst
sub-topic-2.rst
...
\`\`\`
</pre></div>
</div>
<p>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.</p>
</section>
<section id="sphinx-autodoc">
<h2>Sphinx autodoc<a class="headerlink" href="#sphinx-autodoc" title="Link to this heading">#</a></h2>
<p>Sphinx’s <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">conf.py</span></code> file, autodoc is enabled by adding <code class="docutils literal notranslate"><span class="pre">&quot;sphinx.ext.autodoc&quot;</span></code> to
the extensions list. <code class="docutils literal notranslate"><span class="pre">&quot;sphinx.ext.viewcode&quot;</span></code> can also be added to provide
links to source code.</p></li>
<li><p>Documents are actually generated by calling the <code class="docutils literal notranslate"><span class="pre">sphinx-apidoc</span></code> CLI command. The
current Makefile uses the following call:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>sphinx-apidoc<span class="w"> </span>--module-first<span class="w"> </span>-o<span class="w"> </span>docs/sphinx/_autoref/<span class="w"> </span>localsys
</pre></div>
</div>
<p>This writes the automatically generated docs for modules in the package at the
local directory <code class="docutils literal notranslate"><span class="pre">localsys/</span></code> to the <code class="docutils literal notranslate"><span class="pre">docs/sphinx/_autoref</span></code> directory. These are
reStructuredText files by default.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">sphinx-apidoc</span></code> options <a class="reference external" href="https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html">here</a>, as well as more advanced config
<a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#">here</a>.</p></li>
</ul>
</li>
</ul>
</section>
<section id="markdown-syntax">
<h2>Markdown syntax<a class="headerlink" href="#markdown-syntax" title="Link to this heading">#</a></h2>
<p>The <code class="docutils literal notranslate"><span class="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
pages:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>\`\`\`{toctree}
:maxdepth: &lt;n&gt;
:caption: &lt;caption&gt;
:hidden:
example-file-1
example-file-2
example-dir/index
...
\`\`\`
</pre></div>
</div>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">:maxdepth:</span></code> limits the depth of nesting</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">:caption:</span></code> title for the group of pages</p></li>
<li><p><code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="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
pages:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>\`\`\`{include} README.md
\`\`\`
</pre></div>
</div>
<p><strong>Reference directives</strong></p>
</section>
</section>
</article>
</div>
<footer>
<div class="related-pages">
<a class="prev-page" href="index.html">
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Documentation</div>
</div>
</a>
</div>
<div class="bottom-of-page">
<div class="left-details">
<div class="copyright">
Copyright &#169; 2023, Sam Griesemer
</div>
Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
<a href="https://github.com/pradyunsg/furo">Furo</a>
</div>
<div class="right-details">
</div>
</div>
</footer>
</div>
<aside class="toc-drawer">
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
On this page
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Sphinx</a><ul>
<li><a class="reference internal" href="#detailed-directory-structure">Detailed directory structure</a></li>
<li><a class="reference internal" href="#sphinx-autodoc">Sphinx autodoc</a></li>
<li><a class="reference internal" href="#markdown-syntax">Markdown syntax</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
</div>
</div><script src="../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../_static/doctools.js?v=888ff710"></script>
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../../_static/scripts/furo.js?v=32e29ea5"></script>
</body>
</html>
Reference in New Issue Copy Permalink