[SciPy-dev] Guide to NumPy/SciPy Documentation and Sphinx

[Pauli Virtanen]

On 2009-06-15, David Goldsmith <d_l_goldsmith@yahoo.com> wrote:
[clip]
> Are you saying that presently, Sphinx (or at least the way we 
> have it configured) is not completely compatible with _either_ 
> of these conventions (albeit with the nature of the 
> incompatibility differing between the two)?

Yes, Sphinx off-the-shelf is not compatible with the docstring 
format we use. We have a custom plugin that takes care of this.

The only "problem" is the use of section headers. These are valid 
reStructuredText, but they cannot be used inside Sphinx's 
function:: etc. directives, which causes the problems. So we have 
a custom plugin to Sphinx that reformats them.

> Is there not a third option we could adopt which would be 
> Sphinx-compatible "off the shelf"?

When Numpy documentation guidelines were kickstarted, Sphinx did 
not exist, so Sphinx-compatibility was not on the top of the list 
at that time :) The aims in the format were that it would both be 
easy to read via online help and a valid subset of RST, so that 
it could be easily used in documentation generation tools (and so 
it turned out to be with Sphinx).

Sphinx itself does not enforce *any* formatting rules on the 
docstrings, except that they conform to a subset of valid 
reStructuredText (but one where section headers are not allowed 
in autodoc...). To ensure uniformity and clarity, however, we do 
need more structure than that, especially as the documentation is 
currently written by a large number of people.

I think we're doing currently quite well, and having directly 
Sphinx-compatible docstrings would not be a major benefit at this 
point.

Cheers, 
Pauli