Open mattjbr123 opened 2 months ago
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:
autodoc
and autosummary
extensions are essential. doctest
is also useful as it checks any code examples you put in your documentation actually workautosummary_generate = True
to enable the autosummary extensionThe 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:
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
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.