Write doc-strings for all relevant Python code

NikoOinonen commented 2 years ago

Now that we have the sphinx docs up and running we can start adding doc-strings to all the Python functions/classes that we want to be public facing and the result will be automatically added to the web page at https://ppafm.readthedocs.io/en/latest/

NikoOinonen commented 2 years ago

Let me put here some information on how the documentation system works.

Basics

The documentation is built using sphinx, which is a system for building html pages for Python APIs with little effort. The source code for the documentation is located in the repo at doc/sphinx/source. There you find a file called conf.py, which has some configuration options for how the documentation is built and how it looks, as well as bunch of files with the .rst extension, which determine what content the built html pages have.

Writing docstrings

Sphinx uses the reStructuredText (reST) format for it's content. It's a markup language like Markdown that is used here in Github, but with different syntax. However, reST is often not very readable, so I chose to use the napoleon extension in sphinx that allows writing the docstrings in Google-style, which is more readable. A docstring in this style looks like the following:

def example_function(arg1, arg2):
'''
A plain language description of what the function does. This is followed by a list of arguments
and (possibly) return values.

Arguments:
    arg1: Description of argument 1.
    arg2: Description of argument 2. If the description for the argument is very long,
        it can be split into multiple lines.

Returns:
    ret1: Description of return value 1.
    ret2: Description of return value 2.
'''

Notice the empty lines between the description and the arguments and the return values. Also notice that all of the arguments and return values are indented at the same level. These are necessary for the content to be correctly parsed.

You can also use any directives supported by reST such as making links to other functions, classes, or methods:

A link to a class in the same module: :class:`myClass`
A link to a method in the same module: :meth:`myMethod`
A link to a function outside the current module: :func:`.MyFunc`. Notice the dot before the function name that allows for search outside the current module.

For an example of a working docstring, see the AFMulator class: https://github.com/Probe-Particle/ProbeParticleModel/blob/432989deb76284ef4bc29f847e6fb2bab8348731/pyProbeParticle/ocl/AFMulator.py#L18-L55 I have chosen to write the argument descriptions in the format that it first tells the expected type(s) of the argument and then has a explanation of what the argument means. This is probably a good format to follow.

What goes into the doc pages

The structure of the doc pages is determined by the instructions in the .rst files in the source folder. The index.rst file is for the landing page and the other files are for the modules in the package. Inside the files you find directives such as

.. automodule:: ppafm.ml.Generator
   :members:
   :undoc-members:
   :show-inheritance:

This tells that in this place in the document, there should be an automatically generated documentation for all the members in the module pyProbeParticle.ml.Generator along with some options of what should be included. The directives are determined in the autodoc extension for sphinx. For the most part you don't need to modify these, unless you add a completely new module, or remove or rename an existing module, or want to have more control over what appears in the doc pages. By default, all members (classes, functions, methods) except those that start with an underscore _ are included.

Building the docs

Since we setup a workflow with readthedocs, the doc pages will get automatically built and hosted at https://probeparticlemodel.readthedocs.io/en/main every time there is a commit to the main branch. However, you might also want to manually build the html pages on your local machine to test how your new code and docstring looks like in the built docs before a commit. For this you need to have the packages sphinx and furo installed in your active environment. These are installed automatically if you install ppafm with the [dev] option: https://github.com/Probe-Particle/ppafm/wiki/For-Developers#enable-pre-commit-hooks.

Navigate in the repo to doc/sphinx and issue the command

make html

and after the build is done you will find the result in a new folder build/html under the current directory. Open the generated index.html in your browser to view the built doc pages.

Sometimes when making changes, the changes may not seem to appear in the built document even after a rebuild. In these cases it may help to do a hard refresh in the browser (e.g. Ctrl+F5 in firefox) so that the browser cache is dropped. Otherwise, deleting the entire build directory may help.

Note: DO NOT push the build directory to the repository. It is already included in the .gitignore so this should not be easy to do on accident.

NikoOinonen commented 9 months ago

I mentioned in the meeting that I had written some instructions about the sphinx documentation. That's here in the previous comment. I also added it to the wiki now under the For Developers page to make it easier to find.

@yakutovicha @ondrejkrejci @mondracek @aureliojgc

Probe-Particle / ppafm