Re: [Python-Dev] [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 .

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:
.
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 ([EMAIL PROTECTED]),
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
> 
> 
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Lea Wiemann]

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

No need to; we can just fall back to no syntax highlighting if Pygments
is not installed on the user's system.

[Gael Varoquaux]
>> - The html syntax highlighters.   (Pydoc can use those)
>
> I have a patch on the docutils patch tracker that does this.

For everyone's reference,
.

Best wishes,

Lea
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Lea Wiemann]

Martin Blais wrote:

> e.g. are you still marking classes as classes
> and functions as functions in the ReST source

It seems so (modulo XXX's and TODO's in Georg's implementation, probably
^_^) -- all of the pages have "show source" links, so you can see for
yourself.  I'm not an expert with the documentation system, but the
markup on  looks pretty
complete to me.

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

While it's probably not possible to simply generate the documentation
from the docstrings, it would certainly seem interesting to get have
some means (like a directive) to pull docstrings into the documentation.
 I think however that while migrating the docs do reStructuredText is
comparatively straightforward [1]_, pulling documentation from the
docstrings will require quite a bit of design and discussion work.  So
I'd suggest we postpone this idea until we have a working documentation
system in reStructuredText, so we don't clutter the discussion.

.. [1] I'm sure there will still be quite a few issues to sort out that
   I'm simply not seeing right now.

Best wishes,

Lea
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com