[SciPy-dev] docs.scipy.org -- new site for the documentation marathon
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 <firstname.lastname@example.org> 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 , 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 , 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 .
..  http://docs.python.org/library/optparse.html
More information about the Scipy-dev