# Writing Documentation

The documentation is found in `docs/source` and can be written in either Markdown ([MyST](https://mystmd.org/)) or [reStructuredText](https://www.writethedocs.org/guide/writing/reStructuredText/).

## Building Locally

:::{note}
`pdflatex` and `graphviz` are optional but recommended docs dependencies that are required to build the minimal example PDFs and certain diagrams respectively. The documentation can still be built without them however.
:::

Run the following from the root directory to build the docs:

```shell
$ sphinx-build -v docs/source docs/_build/html
```

Then, use a browser to open the html files in `docs/_build/html/`.

## Adding a New Page

`docs/index.md` contains a "table of contents tree" ([toctree](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree)) that defines which pages are included in the top level of the sidebar.

Alternatively, you might wish to include it in a lower level, such as how the individual filters don't appear immediately in the sidebar. See `docs/filters/index.md` for how this is done, and note that the file is itself in the top-level toctree.

When writing a new page, be sure to include it in a tree!

## Filters

The [documentation for the filters](../filters/index) is auto-generated for each one in `in2lambda/filters` every time the docs are built.

The process uses data from two files present in each filter's source code directory:

- `filter.py`: Provides the top-level summary via the file's [docstring](https://peps.python.org/pep-0257/#what-is-a-docstring).
- `example.tex`: This is compiled into a PDF that's embedded into the page.

There should then be no need to write explicit documentation for any new filters since it's all done automatically!

:::{admonition} How the Auto-Generation Works
:class: dropdown

A script was written in `docs/filters.py` that generate the docs. It's called in `docs/conf.py` which is loaded when building the docs. The filters script goes through each directory present in `in2lambda/filters` to determine the docstring (via `__doc__`) and compile the LaTeX file present.

Compiled PDFs are stored in `docs/_static/pdfs` and the generated RST docs are put in `docs/filters/_autosummary`. `docs/filters/index.md` includes these autogenerated files in the website via a [table of contents tree](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree).
:::

## Reference

The [CLT reference](../reference/command-line) is generated based on the output of `in2lambda --help` via [sphinx-click](https://sphinx-click.readthedocs.io/en/latest/).

[API documentation](../reference/library) is built based on [docstrings](https://peps.python.org/pep-0257/#what-is-a-docstring) found within the code base. This is done using [sphinx.ext.autosummary](https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html).

:::{tip}
See the [Set docs](../reference/_autosummary/in2lambda.api.set.Set) and the source code buttons on its page for good examples on how to write the docstrings effectively.
:::