Add documentation (at least for public functions)

[simon-wacker]

Use Google style docstrings for documentation and Sphinx to extract the documentation and turn it into HTML pages.

[bbuenoun]

When I run 'make html', I get the following warning: /net/p/600/groupdrives/620_eeb/621_sbe/Aktuell/Berechnungsprogramme/Fener/ossfener/trace-glare/getting_started.rst:103: WARNING: undefined label: custom_look (if the link has no caption the label must precede a section header)

The resulting html page doesn't look like the sphinx site.

[simon-wacker]

1. In conf.py I had to add the line master_doc = 'index'. Otherwise sphinx complained about the file contents.rst being missing. Maybe this error appears on my machine and not on yours because we use different versions of sphinx.
2. In the file getting_started.rst there is a reference to custom_look. However, custom_look is nowhere defined, so it cannot be referenced. If you remove the code :ref: `custom_look` inside getting_started.rst that warning disappears and the build succeeds.
3. Do not check autogenerated code like the code generated by sphinx into version control. So, first remove the directory _build and commit the removal (rm -rf _build && git add _build && git commit -m '...'). Then add the line /_build to .gitignore.
4. Put all files regarding the documentation in one directory so that they do not litter the project. For example like I did in the repository fener/docs You can then build the documentation by running the commands as in the Makefile target docs.

[simon-wacker]

Some explanation regarding the Makefile target docs mentioned above: It first runs the command sphinx-apidoc -f -o docs/source . to read the docstring documentation from the Python source code and turn it into rst files in the directory docs/source. Then it runs sphinx-build -b html docs docs/html to read the rst files and turn them into html files in the directory docs/html.

[bbuenoun]

Some errors still occur (see attachment). sphinx_errors.txt

index.html shows code documentation, but it doesn't look like the sphinx site yet.

[simon-wacker]

The first command executed in the sphinx_errors.txt file is already wrong. The correct commands are

        sphinx-apidoc \
        --force \
        -o ./docs/source \
        ./glare
    sphinx-build \
        -b html \
        ./docs \
        ./docs/html

Or just use the GNU Make target docs and run

make docs

[bbuenoun]

make docs works without errors, but the resulting html page doesn't look like the sphinx site yet.

[simon-wacker]

What do you mean by Sphinx site? If you mean https://www.sphinx-doc.org , then yes, that is not how it looks. The theme specified in docs/conf.py is Alabaster and it looks for example like PyInvoke. And that's also how, from a styling point of view (font, font size, font color, code style, heading style, ...) the generated documentation looks (at least the one that is generated on my machine). What is different though is that we do not have a sidebar with navigation items. I just opened a pull request which adds such a sidebar.