Guide to rendering the documentation site using Sphinx.

This document includes:

- The coderdata/docs directory structure

- Sphinx commands

- Guide to updating the documentation site

- Helpful sphinx features


Included in `coderdata/docs/requirements.txt`. Extra installations that enable various sphinx extensions.

- sphinx

- myst-parser - adds support for markdown files

- sphinx-design - provides extra design functions (i.e buttons and grids)

- nbsphinx - enables rendering of .ipynb files

- sphinx_tabs - adds tabbed content components

To build the Sphinx documentation locally, navigate to the `docs` directory and run the `sphinx-build` command. This command processes the content files from the `source` directory and generates the rendered HTML output in the `build` directory.

$ cd ../coderdata/docs

$ python -m sphinx.cmd.build -M html <SOURCEDIR/> <OUTPUTDIR/>

$ python -m sphinx.cmd.build -M html source/ build/

To view the rendered site open `coderdata/docs/build/html/index.html`.

To create a basic sphinx set-up in a local repository use sphinx quickstart command.

$ cd ../repo/docs

$ python -m sphinx.cmd.quickstart

Questions will follow this command and when it prompts if you'd like to separate the source and build directories select yes.

The `conf.py` file is the central configuration file for Sphinx and it determines the behavior and appearance of the generated documentation. Specifically it configures extensions, defines metadata, controls output settings, and customizes sphinx behavior. The `index.rst` file is the starting page for the Sphinx documentation build process. It acts as the root file, linking all other pages and defining the document hierarchy. All other .md and .rst files are added and internally referenced within the index page or within the sidebar.

To update pages navigate to `docs/source`, all .rst and .md files live here. Here a reference of the main pages used for the documentation site.

| Main Pages | File Name | Content |

| -----------------| ----------------------------------------------------------------------- | ------------------------------ |

| Home Page | index.rst | Introduction and Install |

| Usage | usage.md | API and CLI |

| API Reference | APIreference.rst | Sphinx autogenerated docstrings|

| Datasets Included| datasets_included.rst | Datasets overview table |

| Tutorials | tutorials.rst | Deep Learning Tutorial |

| How To Contribute| contribution_guide.rst *includes contribution.md and add_code_guide.md* | Contribution Guide |

Note: When adding pages, reStructuredText files are the most sphinx friendly and allow for use of helpful sphinx features. However, Markdown files can be used and will render properly when the myst-parser extension is used.

To add any new images they will live in `docs/source/_static`. The coderdata_header.png and home_page_graphic.png were made using [canva](https://www.canva.com/). The designs are shared with team members so that they can easily be edited if needed!

The original sphinx theme used is 'sphinxdoc', however, to change certain aspects an additional file custom.css was included to override the sphinxdoc theme. To update the custom theme navigate to `docs/source/_static/custom.css`. Changes to the sidebar can be made in `docs/source/_templates/my_custom_sidebar.html`. Any other custom templates will be added to `docs/source/_templates`.

Note: The sphinxdoc theme is automatically generated during the build command into `docs/build/html/_static/sphinxdoc.css`. It is regenerated everytime sphinx build runs so changes to the theme must be made in custom.css.

- [Sphinx Documentation](https://www.sphinx-doc.org/en/master/index.html)

- [Sphinxdoc Sample](https://sphinx-themes.org/sample-sites/default-sphinxdoc/)

- [Full List of Directives in Sphinx](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-directives)

- .. automodule::

This is used to generate documentation from the package. It is used in API reference.

.. automodule:: <pkg>.module

:members: <function>

:undoc-members:

:show-inheritance:

- .. include::

To include content from another file. Example shows how to render a markdown file when using the include call.

.. include:: guide.md

:parser: myst_parser.sphinx_

- .. image::

.. image:: _static/image.png

:align: center

:scale: 100%