Documentation of the documentation generation

[mattjbr123]

Information is lacking on how the doc-generation works and how to edit the docs, so intend to add this information to the 'Developer' section of the documentation and/or a 'how-to' file in the home directory of the repository, like there is for releasing a new version. Branch for development is doubledoc.

[mattjbr123]

Things to include:

• The documentation workflow seems to be fairly standard and similar to many other projects/repos as far as I can tell.

• Sphinx seems to be the go-to package for documentation of repos

• The github side of things also seems to be fairly standard too. The workflow is as follows:

• There is a github workflows workflow file that calls a standard Makefile which calls Sphinx to compile the documentation from a given 'source' folder full of rst files, to a folder of html, which can be published via github pages.

• Sphinx is basically a converter of markup or 'restructured text' (rst) files to html, which can also read docstrings in code and generate nicely linked together documentation from this

• I'm sure this isn't the only reason, but part of the reason for the convolution of having a Makefile instead of calling sphinx more directly is to simplify the command down to just make html.

• The necessary files and folder arrangement are generated by running the sphinx-quickstart command

• Extra config information for sphinx goes in the conf.py file in the source folder. You can get clever and add lots of customisations to Sphinx, as has been done in this project, but the main ones to add are:

  • Adding the path to the repo from the folder the conf file is in so that it knows where to look when automatically documenting the code
  • The project, copyright, author and version information of the project
  • Various extensions that improve the functionality of Sphinx. For automated code documentation, which is arguably the whole point of Sphinx, the autodoc and autosummary extensions are essential. doctest is also useful as it checks any code examples you put in your documentation actually work
  • autosummary_generate = True to enable the autosummary extension

• The rst files in the source directory contain the text and markdown-ish text you want to have on each page of your documentation (one page per rst file), and special 'directives' that control Sphinx. The most useful being to automatically generate documentation of the various classes/methods/attributes in your project, and link everything together via contents pages/tables or 'TOCtrees'.

• The main/root page of the documentation is the index.rst file in the source directory. This is usually where the main table of contents ('TOCtree') lives.

• These TOCtrees are a big feature of Sphinx, and link everything together.

The key need to knows for UniFHy:

• Everything to do with the documentation is in the docs folder
• All the rst files to edit are in docs/_doc_src
• The docs are split into 3 main prose-style (i.e. not specifically documenting the code functions) sections: Users, Developers and Contributors
• The API Reference section is the main bit where all the classes/functions/methods/attributes that make up the code are documented
• Then there is a 'Science Library' section which attempts to pull together documentation about the various models that have been adapted to run on UniFHy
• All 5 sections have 'root'/landing pages of similar names in _doc_src (e.g. users.rst) and folders in _doc_src containing the documentation pages within them
• Any pages added to these folders/sections need to also be added to the toctrees in the corresponding landing pages
• For example to add a new page to the Developers section of the documentation, add the rst file to the developers folder, then add a reference to this file in the table of contents in the developers.rst file. This ensures that the new page will show up in the contents table of the landing page of the Developers section of the documentation
• The rst files in the methods and attributes folders of the api folder are generated automatically by Sphinx, but those in the classes are not
• Any new methods or attributes again need to be added to the toctree in the rst file in classes of the class that they belong to
• There is a UniFHy-specific sphinx extension in the _doc_ext folder and enabled in extensions in conf.py, which automatically generates the documentation for the 'science library' models. To work correctly the models need to be added to the toctree in the appropriate component file(s) in the 'science' folder, and added to the components of the workflow yml file, for all the components they make up
• Images, which are linked to from rst files (example here) and displayed in the corresponding html documentation pages are stored in the _doc_img folder
• Copies of the html files for each release/version of UniFHy are in the version numbered folders (e.g. 0.1.0 and 1.0.0)
• The latest version of the html files are mixed in with all the other folders mentioned (which is not ideal imo) above. You can see which folders and files by looking in the version numbered folders. These are the folders/files not to edit, both in the version numbered folders and those in the main docs folder.
• I'm not sure exactly what the files in _static and _panels_static are other than style sheets and other html webpage gubbins, but I think it's all generated by Sphinx and can be ignored.