[SciPy-dev] docs.scipy.org -- new site for the documentation marathon

Pauli Virtanen pav@iki...
Sun Oct 26 12:41:07 CDT 2008


Sun, 26 Oct 2008 12:41:28 -0400, Nathan Bell wrote:

> On Sun, Oct 26, 2008 at 10:13 AM, Pauli Virtanen <pav@iki.fi> wrote:
>>
>> Now, the role of docs.scipy.org warrants discussion, because on the one
>> hand, the domain "docs.scipy.org" looks very official, and on the other
>> hand, "scipy.org/Documentation" claims to be the place for official
>> documentation. What do you think: should we use the current front page
>> of docs.scipy.org, shifting the focus and entry point of documentation
>> to the Sphinx-generated pages, or still keep the focus on the Moin wiki
>> at scipy.org?
>>
>> I'd like to see a move towards a full dedicated documentation site -- I
>> believe using Sphinx is the way to go in the future, and documentation
>> generated by it does have a reassuring and clear visual appearance.
>> Also, making the Sphinx documentation more prominent could help people
>> to focus documentation efforts, and write more of it :)
>
> Great work, I definitely like the look of the Sphinx documentation.
> 
> As a concrete example of your question, I've been working on some
> scipy.sparse documentation [1], and it seems like it will be fairly
> lengthy when completed.  Would it be appropriate to merge it into the
> Sphinx documentation for scipy.sparse [2], or should the Sphinx docs be
> more concise?

I think we will in the end need both brief API reference documentation 
(docstrings etc., explanations of common semantics such as dtype 
specifications) and then more detailed usage documentation. The current 
Sphinx docs are brief because they almost exclusively contain only the 
former, and for Scipy, mostly only the docstrings are there.

To me, it would make sense to keep all the documentation as closely 
integrated as possible -- then you can use Sphinx's cross-referencing, 
indexing, glossary, math, etc. facilities, and the documentation will be 
easy to find, searchable, and have consistent appearance.

So, I'd like to see your work merged to the Sphinx docs. If I was writing 
the scipy.sparse documentation, I would probably do something like the 
following: one page, say scipy.sparse-reference.rst for a terse listing 
of the API of the package (something like what's currently there), and 
then dedicate as many pages as necessary for more narrative usage 
documentation (what you are writing). Or, I'd put everything on one page, 
as done eg. in Python's optparse documentation [1].

.. [1] http://docs.python.org/library/optparse.html

-- 
Pauli Virtanen



More information about the Scipy-dev mailing list