[Doc-SIG] [Python-Dev] The docs, reloaded

[Martin Blais]

Hi Georg
Super impressive work! :-)

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?

My beef with using ReST for documentation, as much as I like ReST, is
that unless we have roles and structure for declaring functions,
classes, etc. it would remain inferior to the LaTeX macros, which in
spite of being LaTeX, qualify the kinds of objects to some extent.

Wow, it looks amazingly good.  Amazing work.  Very impressed.

(Somewhat related, but another idea from back then, which was never
implemented IMO, was to find a way to automatically pull and convert
the docstrings from the source code into the documentation, thus
unifying all the information in one place.)



On 5/19/07, Georg Brandl <g.brandl at gmx.net> wrote:
> Hi,
>
> 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>.
>
> 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
>
>
> --
> 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.
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/blais%40furius.ca
>