[Doc-SIG] The docs, reloaded

[Lea Wiemann]

Georg Brandl wrote:

> over the last few weeks I've hacked on a new approach to Python's documentation.
> As Python already has an excellent documentation framework, the docutils, with a
> readable yet extendable markup format, reST, I thought that it should be
> possible to use those instead of the current LaTeX->latex2html toolchain.
>
> For the impatient: the result can be seen at <http://pydoc.gbrandl.de>.

Awesome, that looks pretty amazing!

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.

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.)

Your effort and mine only seem to have some limited overlap.  I see that
you added at least some markup to reST that allows documents to be
marked up in a similar fashion as the current Python-specific LaTeX
markup, which is on my list, too.  If you see more overlap, please let
me know, because I may need to adjust my time-line or project-scope
(which is totally fine with me, by the way, so don't worry about
"getting into the way of my project" or so!).

May I suggest we continue the discussion on Doc-SIG only and prune
Python-dev from the CC?  I'm on Jabber/GoogleTalk (LeWiemann at gmail.com),
by the way, so feel free to IM me.

Best wishes,

    Lea


[Rest of the quoted message below.]

> I've written a converter tool that handles most of the LaTeX markup and turns it
> into reST, as well as a builder tool that adds many custom directives and roles,
> and also features like index generation and cross-document linking.
> 
> (What you can see at the URL is a completely statical version of the docs, as it
> would be shipped with the distribution. For the real online docs, I have more
> plans; I'll come to that later.)
> 
> So why the effort?
> 
> Here's a partial list of things that have already been improved:
> 
> - the source is much more readable (for examples, try the "view source" links in
>    the left navbar)
> - all function/class/module names are properly cross-referenced
> - the HTML pages are generated from templates, using a language similar to
>    Django's template language
> - Python and C code snippets are syntax highlighted
> - for the offline version, there's a JavaScript enabled search function
> - the index is generated over all the documentation, making it easier to find
>    stuff you need
> - the toolchain is pure Python, therefore can easily be shipped
> 
> What more?
> 
> If there is support for this approach, I have plans for things that can be added
> to the online version:
> 
> - a "quick-dispatch" function: e.g., docs.python.org/q?os.path.split would
>    redirect you to the matching location.
> - "interactive patching": provide an "propose edit" link, leading to a Wiki-like
>    page where you can edit the source. From the result, a diff is generated,
>    which can be accepted, edited or rejected by the development team. This is
>    even more straightforward than plain old comments.
> - the same infrastructure could be used for developers, with automatic checkin
>    into subversion.
> - of course, plain old comments can be useful too.
> 
> Concluding, a small caveat: The conversion/build tools are, of course, not
> complete yet. There are a number of XXX comments in the text, most of them
> indicate that the converter could not handle a situation -- that would have
> to be corrected once after conversion is done.
> 
> Waiting for comments!
> 
> Cheers,
> Georg
> 
>