Documentation and Docstring Format

[Kamil Paral]

> > https://pythonhosted.org/an_example_pypi_project/sphinx.html#auto-directives
> > 
> > 
> > I'm not suggesting that we drop everything and fix all the docstrings
> > right now but I am suggesting that we start following the sphinx
> > docstring format for new code and fix other-formatted docstrings as we
> > come across them.
> > 
> > Any objections?
> 
> Well, my only objection is, that the Sphinx format has IMHO the worst impact
> on how docstrings look.

That is my impression as well [1]. The improved versions of Markdown are more legible and easier to remember than ReST (+Sphinx) [2]. OTOH, there are certain Sphinx features that look really great (for example documentation of attributes or global variables). So let's try it. 

[1] http://sphinx-doc.org/domains.html#info-field-lists
[2] http://www.unexpected-vortices.com/doc-notes/markdown-and-rest-compared.html

> Maybe it is just me, but I use help() more often than html docs.

The Spyder editor shows HTML output of docstrings, even though it seems it uses plain ReST conversion instead of Sphinx conversion.

> 
> But other than that, I have no issues.

I played with it a little and the syntax is quite complex. If we are to use it, we will need at least:
1. basic sphinx config committed into the repository
2. some instructions in the readme how to generate the docs

so that we can at least generate the docs locally and look at it before posting the patch. As Tim already said, sphinx is pretty strict in its syntax.


There is one more alternative, I think - use Sphinx for docs generation, but keep the docstrings free-form (I assume there must be an option in Sphinx to do that). That way we lose some pretty formatting, but won't be forced to adhere to a particular syntax.