Documentation
Setup
Python
The build process relies on sphinx and uses the sphinx-rtd-theme.
Those packages are installed by setupDevInterpreter.ps1 else execute:
pip install sphinx
pip install sphinx-rtd-theme
to setup your python interpreter.
Js-Doc
To document the js-Frontend jsdoc is used.
For the package to work you need a working installation of node.js that is available in the terminal used to create the
documentation.
npm --version
has to produce a output like 10.9.3 whereas the specific version does not matter.
then install jsdoc with
npm install jsdoc
Assert that
npx jsdoc --version
produces output like JSDoc 4.0.5, version must not match.
Build the documentation
Run
python .../Inskale/Pyodide/Scripts/buildDocs.py
- That will build
python API Documentation of simplipfy package
python documentation of handwritten files in
.../Inskale/simplipfy/docs/sourcejs API Documentation of the front end
the front end documentation is then copied from .../Inskale/Pyodide/src/docs to
.../Inskale/simplipfy/docs/_build/source/frontendAPI. All files that need to be released for the new documentation
are in .../Inskale/simplipfy/docs/_build.
Manually create the documentation
Navigate into .../Inskale/Pyodide/Scripts. From there generate the documentation.
For the sphinx part run:
sphinx-apidoc -f -o ../../simpliPFy/docs ../../simpliPFy/simplipfy
sphinx-build -b html ../../simpliPFy/docs ../../simpliPFy/docs/_build
For js doc
npx jsdoc -c ..\..\simpliPFy\docs\jsdoc.json
There is no output expected if the generation succeeds.
We need to change the directory because the python build script has this directory as its working directory, otherwise
the relative path for jsdoc from the jsdoc.json at .../Inskale/simpliPFy/docs and sphinx are not correct.
Then move all files from .../Inskale/Pyodide/src/docs to …/Inskale/simplipfy/docs/_build/source/frontendAPI``
you may have to create the frontendAPI folder. All files needed for a new release of the documentation are now in
.../Inskale/simplipfy/docs/_build.