Should we consider fully automated documentation?

[MaxvdKolk]

Not much experience with fully automating these documentation pages..., but it seems that sphinx-apidoc can generate all the *.rst files required to set up the documentation based on the doc strings.

The docs it generates does feel rather robotic, every (sub)package and module are labelled as such... And I wonder if we should opt for a more manual approach, or some intermediate route, where we put some more effort in setting up the *.rst files to get a bit less robotic vibes.

Thoughts?

PS You should be able to generate the docs using make docs if you have sphinx and the apidoc extension installed locally.

[artofscience]

@MaxvdKolk maybe we can look for alternatives to sphinx?

[MaxvdKolk]

Yeah, might be nicer, or to figure out a way to configure sphinx better to get some nice output. I will require something like this for work soon too, so maybe we postpone till I have figured it out for that?

Of course, if someone has a better solution in the meantime, I would be interested :^)

[MaxvdKolk]

I think we might still want to consider Sphinx, as it has a bunch of great features. The direct output of the automatic documentation generation was just rather robotic and verbose. To counteract that, I added the docs/source/*.rst files into the repository and edited parts manually.

This has the advantage of being able to control the titles and layout in more detail, with the downside that if class layouts change we need to reflect those changes manually in the documentation as well. However, this is relatively simple, see the added files here b280bbff66bed60fce5caa37c47a1739932c6109.

Note: all the contents for each module is still automatically generated using autodoc, e.g. this is the only code required to generate a section

Problem
-------

.. automodule:: sao.problems.problem
   :members:
   :undoc-members:
   :show-inheritance:

I think it looks all right, what do you guys think?

---

My proposal would be to add more details to the docstrings to further improve the content of the documentation as well as add separate pages in the Examples section that discuss various problems / main files.

If you are OK, we can merge I think.

[Giannis1993]

Nice addition Max, the manual version looks beautiful! Content-wise there is indeed some polishing to be done.