Refactor docstrings in utilities. Remove redundant/unused modules. (!466) · Merge requests · OpenFlexure / openflexure-microscope

Start to move docstrings to a new style this MR is suggested for instead of !411 (closed). This style is being introduced into SCA2D as it adds documentation features.

The docs packaged with (but not linked to in) the assembly documentation. At the url <root-assembly-url>/scad_docs/index.html

Why change docstring style

This style differs from openscad_docsgen. This is because openscad_docsgen cannot read SCAD code so it needs all information presented to it. Some issues with their syntax are:

Requires a complex set of nested and specific information to give it context. Information that is set by indentation and headers. It creates a lot of boilerplate, and falls over if anything is missing.
Requires function/module name and signature to both be re-written above the definition in SCAD. The definition in the docs is reported. As such it can easily get out of data.
Using single line comments makes it slow to write and adjust documentation (there may be tools for this)

On the other hand the syntax here is modelled on Python docstring conventions. Except that the docstring is above the module/function definition, not on the first line after the signature. This was needed because there are no new lines following the function signature, just an =. In the new syntax, SCA2D can:

Create basic documentation for a file with no docstrings from its modules and functions. Each with with arguments and defaults.
It is possible to simply start adding docstrings one function at a time, without having to add complex file-level docstrings and section docstrings first.
A docstring can be as simple as a quick sentence. It will be added to the docs as this is better than nothing. More structured parameter definitions can be layered on later.
SCA2D can detect these docstrings and warn if they are missing, have the wrong argument list.

Considerations for using SCA2D over `openscad_docsgen`:

Pros

Lots more automation. Including module/function signatures and also an option to view source.
We control the backend and can add features as needed
openscad_docsgen is mostly focussed on building docs for the BOSL2 scad library that are deployed on GitHub wiki. In the past @rwb27 and I have both opened PRs to make it work for our use case, but this tends to get broken in future updates
Creates reactive HTML, not just markdown

Cons

Less control over how examples show (Though there is a lot of low hanging fruit for improving this)
We end up maintaining another documentation program.
The HTML is quite basic