Documentation in Sphinx

[mgielda]

Hi all,

I'd like to propose that I set up some documentation in Sphinx for the project, incorporating what is there so far but making it possible to easily build HTML and PDF docs for everyone. Sphinx is the de-facto standard documentation system for Python, so I think it makes sense, and it's a known system with lots of manuals so people can contribute easily.

This way we could even push it to Read The Docs later - give it more exposure + get automagic builds available on the Web.

What do you think? @olofk I assume this is a question to you mostly :) ?

[olofk]

I know next to nothing about best practices for documentation, so I trust your judgement on this. Please let me know what I need to do to make this happen. In case you haven't seen it, most of the (very sparse) documentation is static asciidoc right now, except for capi1.txt which is dynamically generated from section.py

[olofk]

One thing that would be great is if Sphinx can pull together the static documentation with pydoc stuff. There is currently zero pydoc in the code, but this would give me a good reason to finally document the API between all the modules

[mgielda]

Basically I can prepare a pull request in my cough cough spare time. Should not be terribly hard given that currently we don't have very much docs to convert!

As for pydoc, if I understand correctly you would want to document functions with docstrings and be able to use that from within Sphinx. See the documenting objects section of the Sphinx tutorial, especially the autodoc subsection.

The built-in autodoc extension is used when you need to document code automatically though it is not recommended to abuse it as this leads to a very generic Doxygen style docs which Sphinx was created in opposition to (the idea is to write up a human readable documentation and refer to function definitions etc. when necessary, not as an excuse to not write proper usage manuals ;))

[olofk]

Documentation is currently in asciidoc. Converting to rtd would be an enhancement, but not a priority right now

[mithro]

@olofk - I think this should be a high priority. I probably wouldn't use a Python library which didn't have published Sphinx documentation (which is super easy to do with readthedocs).

[olofk]

Done! :) https://fusesoc.readthedocs.io/en/master/