Documentation Guide

Code Documentation Philosophy

The philosophy of documentation in the Healthy Meals project is to have the documentation be part of what is being documented (aka: Docs as Code).

The choice to use the google style documentation was motivated by an sphinx article on napoleon legible docstrings. It is recommended to use one style through out a project, and the google style seems to be more popular, especially for non-scientific applications.

Using docstrings for code documentation:

Code Documentation Process Overview

Code is being documented using the Sphinx toolset, which is the defacto standard tool for documenting django/python. The Sphinx toolset recognizes NumPy , Google , and rst code documentation standards. This is achieved by using the Napoleon extension to Sphinx. When code has docstrings appropriately placed within it, Sphinx will automatically pull them into the documentation in the docs directory. The healthy-meals github repository has been set up to automatically deliver the documentation to a github pages site on the internet.

Example Google Style Docstring for a function:

def example_function(param1, param2):

“””Summary of the function.

Detailed description of the function.

Args:
param1 (int): Description of the first parameter.

param2 (str): Description of the second parameter.

Returns:
bool: Description of the return value.

Raises:
ValueError: If param1 is negative.

Examples:

$ example_function(1, “test”)

True

“””

Generation of the Documentation.

nox is the automation tool we use generate or update the documentation that will eventually produce HTML documentation in the docs/build folder. See our nox guide about our use of nox in healthy-meals. We use the github pages style of docstrings for the documentation of healthy-meals. The details of the steps that we follow to generate the documentation are:

Sphinx is used to generate the documentation, which ends up as HTML pages in the docs directory. We have a nox automation command that does all of this:
```
"nox -s sphinxDocs"
```
The sphinxDocs nox session (script) does the following:
1. Remove all prior versions of the documentation from the docs directory:
```
session.run("pdm", "run", "rm", "-fr", "./docs/build")
session.run("pdm", "run", "rm", "-fr", "./docs/source")
session.run("pdm", "run", "cp", "-R", "./docs/sphinx_src/", "./docs/source/")
```
  These commands first remove the source and build directories from the docs directory. We then copy all of the files in the docs/sphinx_src directory into a new clean docs/source directory.

First, confirm you are in the root directory (directory containing manage.py)

Caution: The Sphinx setup was initially run with the command sphinx-quickstart docs, making docs/ as the documentation folder. If you are not using the nox automations generating the documentation you should:

be in the root directory of the project (where manage.py exists).
specify the doc directory location ( –directory=docs, or -C docs)

The sphinx extension apidoc is used to automatically document code using signatures and docstrings from the code, and place it in .rst files (and then later into .html files).

We needed an exclusion list of modules to ignore because we are not using an apps/ folder. This is because we are following the standard django structure (to have all apps off of root): djangoproject.com (Creating an app). . All exclusions are listed after the ‘.’ (the root folder) see docs/Makefile and docs/source/conf.py.

To Build the Documentation:

We will use nox to run the sphinxDocs automation session, which will: - remove the build and source directories within docs - copy in our manually created rst files into a new docs/source directory from docs/sphinx_src - run nox -s testing to run all of the tests, coverage and generate their badges - run nox -s genNoxDocs to list all of the automations that nox can do.

Note: we create a text file of the nox –list command to display all of the commands (sessions)

Note: we need to do this because sphinx autodoc does not extract the docstrings from noxfile.py.

run sphinx-apidoc to extract docstrings from the project source files into .rst files in the docs/source directory.
run the sphinx-build to generate html in the docs/build directory from the .rst files in the docs/source directory.
This is all done by the following nox command:

nox -s sphinxDocs

# or using Docker
nox -s dockerMakeDocs

# or using make
make apidocs --directory=docs
make html --directory=docs

To Rebuild the Documentation (ensures all old links and pages are gone):

nox -s remakeDocs

# or using Docker
nox -s dockerRemakeDocs

# or using make
make apidocs --directory=docs
make allhtml --directory=docs

The final HTML documention main index page is generated to: docs/build/html/index.html

# or alternatively
make -C docs

# or alternatively
make html --directory=docs

# or alternatively
make html -C docs

# or manually
 sphinx-build -M html docs/source docs/build

Notes: - you may want to review the output of the make for warnings or errors - If you have added any new apps, you should add them to the index.rst file, so they are available at the top level of documentation. - They will automatically show up in docs/source/modules.rst without titles like the ones in docs/source/index.rst

The Sphinx toolset provides the capability of doing this using:

the Toc Tree @ documentation.help extension to manage a Table of Contents.
the sphinx autodoc extension to extract the documentation as well as extract documentation from the code itself.
the sphinx apidoc extension to generate the documentation in the form of .rst (restructured text files).
the sphinx napoleon extension to allow for rst, google or numpy style documentation.
the sphinx todo extension allows for the accumulation of all doc strings (or entries in .rst files) marked as .. :Todo to be automatically included into a To Do List.

Understanding the custom .rst anc config files (docs_guide.rst, index.rst, and conf.py)

The index.rst file is a customized version of the initial one created by sphinx-quickstart.

It has a table of contents that looks like:

Table of Contents
-----------------

.. toctree::
  :maxdepth: 2
  :caption: Contents:

  Quality Assurance</qa>
  Index<genindex>
  Module Index<modindex>
  User Accounts Module</accounts>
  Misc. Pages Module</pages>
  Tests Module</tests>
  Programmers Guide<prog_guide>
  Documentation Guide</docs_guide>

The Table of Contents (TOC) is what shows up in the sidebar navigation. It has been customized in the following ways:

the custom qa tool (labeled Quality Assurance) has been placed at the top to provide access to the testing reports.
the genindex tool (labeled Index) standard utility to provide an index to the entire project.
the modindex tool (labeled Module Index) standard utility to provide an index to all modules of the project.
the /accounts apidoc generated file (User Accounts) module for the Custom User accounts.
the /pages apidoc generated file (Misc. Pages) module for simple pages such as home, or about.
the /tests apidoc generated file (Tests, automated testing doc strings generated documentation.
the custom /prog_guide (Programmers Guide) includes many technical details about how this project has been programmed, philosophy, standards, and the To Do list pulled from the code base and documentation.
the custom /docs_guide (this Documentation Guide file) is added to introduce the documentation philosophy of healthy-meals, and provide a step by step breakdown of the documentation process.

Note: the format of the entries in the TOC is as follows: “The Name With Spaces<[optional /]rst_filename_without_extension>”

The name to display in the TOC.
the name of the .rst file (without the .rst extension) is contained within “<” and “>”.
the name may have a leading optional “/” to ensure that it is always in the (main) TOC.

We build the sphinx .rst files in the docs/source, then build html into the docs/build/html directory.

Note: Sphinx requires that all of the .rst files used to build the documentation reside in the source directory. Because we are using both our custom .rst files (including the index.rst file) and the files generated from the code using the autodoc toolset, this directory is a mix of files that are regenerated, as well as files that are permanent custom files. To prevent accidental loss of any of the permanent custom files (including index.rst), these files are now kept in the docs/sphinx_src directory, and copied into the source directory when using the nox documentation automations.

Caution: Be sure to edit your .rst files in the sphinx_src directory, not the source directory.

The Sphinx Raw Directive is used to have custom HTML for linked images placed initially for the Quality Assurance page.

Linking is provided using Link Documentation.

Code can be displayed using Code Blocks.

Sphinx & Restructured Text (rst) guides and resources:

sphinx tutorial.
Sphinx Docs.
Sphinx @ documentation.help.
The excellent Google Style Python Docstrings.
The sphinxcontrib Module.
Sphinx Idiots Guide.
ianhopkinson.org.uk.
sphinx rtd theme that is used in this project.
One of many possible Cheat Sheets.

Deployment to Github Pages:

See: Pull Requests (in Developer Documentation).

For guidance on how to do Continuous Integration (Testing and validation done in the remote repo - Github), I found this page helpful: Deploying Github Pages with Github workflows. I ended up doing the following:

I Turned off the Jekyl workflow, so that I could run the regular github workflows in the .github/workflows directory.
I then could see my pre-existing .github/workflows/djangoCi.yml action could now run.
I then added another github action to deploy the pages following the instructions by davorg, and now (hopefully ???) the CI tests are run to ensure no automated testing errors, as well as automatic deployment to github pages.