Documentation audit: API does not document __init__

[kitchoi]

API is automatically generated by apidoc, however, that left a number of classes' init not to be documented.

Notably, remoteappmanager.db.orm.AppAccounting and remoteappmanager.db.csv_db.CSVAccounting are referred to by deployment and configuration in the documentation. User needs to know how to initialise them.

The __init__ documentation were manually added in this PR: #147
but then automatically removed by apidoc again in this PR: #189

[stefanoborini]

Found out the following: sphinx-apidoc is not very flexible on this regard. The only option is to use SPHINX_APIDOC_OPTIONS envvar, where we can specify what to include. Once we do so, the "special-members" directive is added, but unfortunately without specifying them explicitly, all dunder members are included in the final docs.

So, the alternative would be to have make apidoc not delete the generated rst files, create them once, and modify them once and for all, but the problem with this approach is that when we add new stuff to existing modules, we have to be a little more manual in refreshing the file: delete the old one, make apidoc, check what was removed, reintroduce the things we care about (eg. special members). Alternatively, take over and do the addition manually.

[itziakos]

Based on my experience using sphinx-apidoc is not the best solution mainly because the resulting rst code is agly.

To have documentation that is actually readable one needs to do the following:

• Use sphinx-apidoc for each top level subcomponent to have a draft in separate directories
• Update index.rst as necessary.
• setup the right global autodoc parameters at conf.py.
• fine tune the generated api files as necessary
• commit the changes

This should be done before every release (The logic can be encapsulated in the documentation makefiles)

• run sphinx-apidoc to generate stub rst for new modules
• fine tune the generated api files as necessary

[itziakos]

I will pickup this issue to provide an example of how to deal with api documentation

[itziakos]

Actually there is a better way using autosummary

[stefanoborini]

Documentation is now restored to working status, and the init methods are now correctly documented. Closing

[stefanoborini]

Particularly, see PR #194 #232 #233 and #234