[Python-Dev] The docs, reloaded

[Georg Brandl]

[warning: bulk answer ahead]

First, thanks for all those nice comments!

[John Gabriele]
 > BTW, would like to see a little blurb of your own on that page about
 > how the docs were converted, rendered, and their new source format.

Sure. I've already written part of the new "Documenting Python" docs, which
cover this a bit. The "About the documentation" will be rewritten too.

[Lea Wiemann]
 > I'd reeeally like to have a look at the source code (don't worry if it's
 > not clean!).  Can you publish or post it somewhere?  If you'd like to
 > store it in the Docutils sandboxes, just drop me a line and I'll give
 > you SVN access.  By the way, things get a lot easier for me if you place
 > it in the public domain, because that's the license Docutils uses, and
 > it's obviously compatible to every other license.

The toolset is now in the Docutils sandbox at
<http://svn.berlios.de/svnroot/repos/docutils/trunk/sandbox/py-rest-doc>.

 > I actually have a Google Summer of Code project, "Documenting Python
 > Packages with Docutils", which I'll start working on May 28:
 > <http://code.google.com/soc/psf/appinfo.html?csaid=8D04C53750906F50>.
 > It has a somewhat different scope, so our projects will complement each
 > other nicely I believe.  (To the point where we may end up with a
 > complete tool-chain to actually migrate the Python documentation to
 > reST.  Très cool.)

Great! Making the new toolset usable for third-party developers is certainly
a good option. I saw quite a few using the LaTeX-based tools too..

[Ron Adam]
 > I've been working on improving pydoc. (slowly but steadily) Maybe we can
 > join efforts as I think the two projects overlap in a number of areas, and
 > it sounds like we are thinking of some of the same things as far as the
 > tool chain.  So maybe there's some synergy we can take advantage of.

Certainly there's plenty of overlap.

 > It looks like there may be a few areas where we can share code.
 >
 >     - The html syntax highlighters.   (Pydoc can use those)

The highlighting is actually done with Pygments, which cannot be included
in the stdlib as-is. Perhaps a stripped-down version?

 >     - A shared html style sheet.
 >     - Document locater.  [1]
 >     - An HTMLServer for local (dynamic dispatching) html viewing. [2]
 >     - The reST source for viewing topics and keywords in pydoc.
 >           (Instead of scraping html pages. Ick)

Yes, that makes sense. If you want to coordinate efforts, feel free to
contact me at Jabber <gbrandl at pocoo.org>.

[Ka-Ping Yee]
 > I agree that interactivity (online commenting and editing) will
 > be a huge advantage.

 > I could imagine this heading in a Wiki-like direction -- where a
 > particular version is tagged as the official revision shipped
 > with a particular Python release, but everyone can make edits
 > online to yield new versions, eventually yielding the revision
 > that will be released with the next Python release.

Yes. I think that always only the latest version should be "publicly"
interactive. Old archived doc versions should be static only.

[Martin Blais]
 > I haven't looked at it in depth yet, but I have a question.  One
 > concern from a long thread on Doc-Sig a long time ago, is that ReST
 > did not at the time possess the ability to nicely markup the objects
 > as LaTeX macros do.   Is your transformation losing markup information
 > from the original docs?  e.g. are you still marking classes as classes
 > and functions as functions in the ReST source, or is it converting
 > from qualified markup to "style" markup (e.g., to generic literals
 > instead of class/function/variable/keyword argument docutils roles,
 > etc.).    If you solved that problem, how did you solve it?  Is the
 > resulting ReST pretty?  Do you think we can build a better index?

As Steven said, it's solved quite nicely with interpreted text roles.
Whether ":class:`Foo`" is nicer than "\class{Foo}" is not entirely clear ;)
but you actually get more now, since if a class "Foo" is found in the
namespace, it will be cross-linked automatically.

About the index: I didn't do anything about it. I just transferred the
LaTeX commands into reST directives, the rest is generated completely
analogous.

 > Very nice! As well as looking very attractive and professional, the all-Python
 > toolset should make it easier to build the documentation - I've not been
 > able to get a trouble-free setup of the docs toolchain on Windows.

Yep. As it is now, you need three packages from the Cheese Shop:
Docutils, Pygments (the highlighter) and Jinja (the templating engine).
This shouldn't be problematic, though they could also be stripped down
and included.

Cheers,
Georg


-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.