[SciPy-dev] docs.scipy.org -- new site for the documentation marathon
Mon Oct 27 18:31:20 CDT 2008
Mon, 27 Oct 2008 15:16:14 -0400, jh wrote:
> I like the Sphinx site!
> But, I like the scipy.org/Documentation URL, since docs are part of the
> package and not a separate project (like, say, ipython.scipy.org). We
> should have a consistent layout of URLs, so that things that are part of
> numpy/scipy are under http://scipy.org/ and things that are not might
> still be hosted on a scipy.org domain but are not directly under
> http://scipy.org/. Is it technically possible/feasible for a Moin site
> to (appear to) include another site underneath it? If not, I'd choose
> function over form, grudgingly.
I don't see a problem having a separate domain docs.XXX -- I think it's
relatively clear to the user what the site contains, and emphasizes that
this is the "official" documentation. Also, several projects, eg. Python,
have a similar layout, so I don't think we are in a bad company with
this). But technically, it would be possible to have scipy.org display
documents residing on docs.scipy.org (eg. using mod_rewrite [P] in apache
-- involving Moin in the process is wasteful).
> For the top page layout, I propose (rationale below):
> (No left sidebar)
The branding on the docs site should probabably be made a bit more
similar to that on scipy.org, and this probably involves deciding what to
do with the sidebar. There should also be an obvious way back to
scipy.org. The muse is silent, so I don't know how the page should look
> DOCUMENTATION EDITOR
> Write, review, or proof the docs!
> MATURE DOCUMENTS
> Guide to Numpy
> PDF book by Travis Oliphant
> DOCUMENT-IN-PROGRESS SNAPSHOTS
> Numpy Reference Guide (as of yyyy-mm-dd) PDF zipped HTML
> refguide glossary shortcut
> Numpy User Guide (as of yyyy-mm-dd)
> PDF zipped HTML
> Scipy Reference Guide (as of yyyy-mm-dd) PDF zipped HTML
Looks good to me. How about combining the "DOCUMENTATION EDITOR" and
> Rationale: We have had a real problem getting a critical mass on doc
> writing. We rallied in the summer, but for the past two months almost
> no contributions have been made (click on stats to see). Originally,
> the only purpose of the site was editing the docs, and someone who
> wanted to read what was current did that through our editing
> infrastructure. This made it very encouraging to edit. Now, when they
> click on "improved docstrings" on scipy.org/Documentation, they instead
> go to a passive presentation of the current content, no editor. They
> have to go to the last link on the page to get into the editor, and the
> text there doesn't scream "Editor!". Until we have *at least* version 1
> of each of our docs, we should keep the edit link first.
It's possible (and easy) to add an edit link on each editable page in the
static documentation. I can add these.
The changes won't, however, be immediately visible in the static
documentation, so maybe clicking the link the first time should show a
> I'm almost ready to say the docs in progress should *only* be
> accessible through the editor (which does present HTML, zipped HTML,
> and PDF) until we have version 1 done.
The problem is that presently not all pages are editable via the
documentation wiki, only the docstrings, so for motivation (including
mine), I think it's important to have a snapshot of the "final" versions
available somewhere. Maybe not linked to with big letters, but still
Issue  is a blocker for this, and one needs to think also about .
..  http://code.google.com/p/pydocweb/issues/detail?id=26
..  http://code.google.com/p/pydocweb/issues/detail?id=27
> We should also remove irrelevant links and text.
[clip: downloads to main page, remove unnecessary links]
Sure, these seem like good improvements.
More information about the Scipy-dev