[SciPy-dev] Guide to NumPy/SciPy Documentation and Sphinx
Mon Jun 15 16:39:40 CDT 2009
On 2009-06-15, David Goldsmith <firstname.lastname@example.org> wrote:
> 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
More information about the Scipy-dev