execlib/docs/reference/documentation/sphinx.md

# 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/