From rrr at ronadam.com  Thu May 17 19:03:29 2007
From: rrr at ronadam.com (Ron Adam)
Date: Thu, 17 May 2007 12:03:29 -0500
Subject: [Doc-SIG] PyDoc discussion
In-Reply-To: <4335d2c40704130602s7fb55a31h974d4442c0dc04e5@mail.gmail.com>
References: <se4po293ji.fsf@pc047299.dhcp.germanlloyd.org>	
	<461E9129.1080300@ronadam.com>
	<4335d2c40704130602s7fb55a31h974d4442c0dc04e5@mail.gmail.com>
Message-ID: <464C8AE1.90001@ronadam.com>

David Goodger wrote:
> On 4/12/07, Ron Adam <rrr at ronadam.com> wrote:
>> Would anyone here be interested in discussing details of the pydoc 
>> rewrite
>> I've been working on?
> 
> Yes, I would like to hear about it, and I think others would too.
> 
>> And is this a good place for that?
> 
> As good a place as any, I'd say ;-)
> You may want to let python-dev & python-list know that a discussion is
> happening here.

After looking at docutils a bit further, I've decided to include a 
formatter to output ReST-text so that the output from pydoc can be used 
with distutils.

If a docstring is already in Rest, it will just pass it though, the output 
of the pydoc sections, lists and items will be formatted in ReST to match.

Then docutils can be used to translate it to other formats.


I'll also try make a formatter that will output a distutils data structure. 
  That will be a bit more difficult but should be doable.  I think the data 
structure I'm using isn't all that different.

In this case pydoc will need to use docutils to parse the doc string.  The 
rest of the documents can be mapped directly to the docutils data structure.


I also want to be able to request (from pydoc) individual parts in a way 
that they can be formatted and then assembled later or included in other 
documents easily.

I'd be interested in hearing any thoughts on these ideas.

Cheers,
    Ron



From amk at amk.ca  Fri May 18 15:59:26 2007
From: amk at amk.ca (A.M. Kuchling)
Date: Fri, 18 May 2007 09:59:26 -0400
Subject: [Doc-SIG] Updating docs.python.org to 2.5.1 docs?
Message-ID: <20070518135926.GA5622@localhost.localdomain>

Does the content on docs.python.org need to be updated to the Python
2.5.1 docs?  The release date on the page is given as September 19,
which is the 2.5 release date.

--amk


From g.brandl at gmx.net  Sat May 19 19:14:09 2007
From: g.brandl at gmx.net (Georg Brandl)
Date: Sat, 19 May 2007 19:14:09 +0200
Subject: [Doc-SIG] The docs, reloaded
Message-ID: <f2nb8o$g7v$1@sea.gmane.org>

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.


From fuzzyman at voidspace.org.uk  Sat May 19 19:19:46 2007
From: fuzzyman at voidspace.org.uk (Michael Foord)
Date: Sat, 19 May 2007 18:19:46 +0100
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <f2nb8o$g7v$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org>
Message-ID: <464F31B2.2090402@voidspace.org.uk>

Georg Brandl 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>.
>   

Wow! Very impressive.

Changing to ReST would encourage more contributions to the documentation 
and widen the range of people able to maintain them.

Michael Foord


From jmg3000 at gmail.com  Sat May 19 21:05:23 2007
From: jmg3000 at gmail.com (John Gabriele)
Date: Sat, 19 May 2007 15:05:23 -0400
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <f2nb8o$g7v$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org>
Message-ID: <65e0bb520705191205p222a5f2by9b04e5793b3cb3e7@mail.gmail.com>

On 5/19/07, Georg Brandl <g.brandl at gmx.net> wrote:
>
> [snip]
>
> Waiting for comments!

Awesome, Georg! Wow. Nice work.

Seems like this has been a long time comin', and I bet others have
been working away "in secret" on similar projects. I hope you keep
running with it until it gets hijacked into being the "official"
versions. :)

I'm bookmarking it as "python docs" in my browser.

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.

Thanks much,
---John

P.S. -- funny sig, btw. :)

From LeWiemann at gmail.com  Sat May 19 22:11:52 2007
From: LeWiemann at gmail.com (Lea Wiemann)
Date: Sat, 19 May 2007 16:11:52 -0400
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <f2nb8o$g7v$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org>
Message-ID: <464F5A08.5010507@gmail.com>

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

From rrr at ronadam.com  Sat May 19 22:31:59 2007
From: rrr at ronadam.com (Ron Adam)
Date: Sat, 19 May 2007 15:31:59 -0500
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <f2nb8o$g7v$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org>
Message-ID: <464F5EBF.4030209@ronadam.com>

Georg Brandl 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>.

Wow, very nice.  I like it.. +1

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.

Some of the things I've recently considered adding to pydoc.

    - To output individual sections for use in a template engine.
    - A reST formatter.
    - Use docutils to format reST doc strings to html in the html
        formatter.  (as an option, not the default.)

It looks like there may be a few areas where we can share code.

    - The html syntax highlighters.   (Pydoc can use those)
    - 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)

(1.) Pydoc has a locater function which finds the html docs and presents a 
link to the html page for an individual item.  But it would be more 
reliable if the dispatcher where on the document end.  Then pydoc would 
have a single place to link to.  (Either locally or on line.)

(2.) The server in pydoc will probably work as is.  You just need to supply 
a callback to get the pages.  It's a separate module now.

Cheers,
    Ron


> 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


From lac at openend.se  Sun May 20 00:11:33 2007
From: lac at openend.se (Laura Creighton)
Date: Sun, 20 May 2007 00:11:33 +0200
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: Message from Michael Foord <fuzzyman@voidspace.org.uk> 
	of "Sat, 19 May 2007 18:19:46 BST." <464F31B2.2090402@voidspace.org.uk> 
References: <f2nb8o$g7v$1@sea.gmane.org> <464F31B2.2090402@voidspace.org.uk> 
Message-ID: <200705192211.l4JMBXP3008746@theraft.openend.se>

Wow.  Nice job.  Thank you so very much.

Laura

From blais at furius.ca  Sun May 20 03:46:52 2007
From: blais at furius.ca (Martin Blais)
Date: Sat, 19 May 2007 18:46:52 -0700
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <f2nb8o$g7v$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org>
Message-ID: <1b151690705191846o45604bc6jcdbc3159513feda1@mail.gmail.com>

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
>

From g.brandl at gmx.net  Sun May 20 10:41:09 2007
From: g.brandl at gmx.net (Georg Brandl)
Date: Sun, 20 May 2007 10:41:09 +0200
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <f2nb8o$g7v$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org>
Message-ID: <f2p1j5$nv$1@sea.gmane.org>

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


From gael.varoquaux at normalesup.org  Sun May 20 11:11:59 2007
From: gael.varoquaux at normalesup.org (Gael Varoquaux)
Date: Sun, 20 May 2007 11:11:59 +0200
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <464F5EBF.4030209@ronadam.com>
References: <f2nb8o$g7v$1@sea.gmane.org> <464F5EBF.4030209@ronadam.com>
Message-ID: <20070520091159.GB14894@clipper.ens.fr>

On Sat, May 19, 2007 at 03:31:59PM -0500, Ron Adam wrote:
>     - The html syntax highlighters.   (Pydoc can use those)

I have a patch on the docutils patch tracker that does this. Code is
probably of a rather bad quality, but it outputs LaTeX and HTML. If we
can work together to improve this patch and get it in docutils it will
avoid having different syntaxes and behavior depending on the front-end
to docutils being used (I am thinking of rest2web, trac, and I am
probably forgetting some others).

The patch has been sitting there for almost 6 months without review, but
I have that if people other than me work on it and ask for review it will
both improve, and get reviewed, and eventually get in !

Sorry for the shameless plug, but I really do think we need a unifying
approach to this.

Ga?l

From LeWiemann at gmail.com  Sun May 20 13:00:31 2007
From: LeWiemann at gmail.com (Lea Wiemann)
Date: Sun, 20 May 2007 07:00:31 -0400
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <f2p1j5$nv$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2p1j5$nv$1@sea.gmane.org>
Message-ID: <46502A4F.4000004@gmail.com>

[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,
<http://sf.net/tracker/index.php?func=detail&aid=1595345&group_id=38414&atid=422032>.

Best wishes,

    Lea

From grubert at users.sourceforge.net  Sun May 20 13:39:46 2007
From: grubert at users.sourceforge.net (grubert at users.sourceforge.net)
Date: Sun, 20 May 2007 13:39:46 +0200 (CEST)
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <1b151690705191846o45604bc6jcdbc3159513feda1@mail.gmail.com>
References: <f2nb8o$g7v$1@sea.gmane.org>
	<1b151690705191846o45604bc6jcdbc3159513feda1@mail.gmail.com>
Message-ID: <Pine.LNX.4.64.0705201338510.7398@lx5.local>

> Hi Georg
> Super impressive work! :-)

looks very good, indeed

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

i thought the libctypes documentation in 2.5 was done with
the docpy-writer, but i might be completely wrong.

cheers

-- 


From blais at furius.ca  Sun May 20 20:08:15 2007
From: blais at furius.ca (Martin Blais)
Date: Sun, 20 May 2007 11:08:15 -0700
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <f2p1io$mr$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2p1io$mr$1@sea.gmane.org>
Message-ID: <1b151690705201108v53f19b39s93e45b915ae80ea7@mail.gmail.com>

On 5/20/07, Georg Brandl <g.brandl at gmx.net> wrote:
>  > 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.

This is great.  IMHO if this is to compete to become the official
Python docs, I would argue for even less dependencies, even at the
cost of more generic/bland output, for portability reasons and to
stimulate greater adoption.  If we can make some of those dependencies
optional and only rely on docutils, that could make it ubiquitous.

Another thing to keep in mind:  I don't know if the directives you
defined are very generic, but if they are, it would be interesting to
consider migrating them up into docutils (if it makes sense), and see
if they could support documenting other programming languages.  Could
this be a language-independent documenting toolkit?  Could we document
LISP or Ruby code with it?

Georg, thanks again!

From ndbecker2 at gmail.com  Sun May 20 22:52:12 2007
From: ndbecker2 at gmail.com (Neal Becker)
Date: Sun, 20 May 2007 16:52:12 -0400
Subject: [Doc-SIG] The docs, reloaded
References: <f2nb8o$g7v$1@sea.gmane.org>
Message-ID: <f2qcds$8b9$1@sea.gmane.org>

Sounds very interesting.  I just have one concern/question.  I hope that
while moving away from latex, we are not precluding the ability to write
math as part of the documentation.  What would be my choices for add math
to the documentation?  Hopefully using latex, since there really isn't
AFAIK any other competitor for this.


From aahz at pythoncraft.com  Mon May 21 00:42:21 2007
From: aahz at pythoncraft.com (Aahz)
Date: Sun, 20 May 2007 15:42:21 -0700
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <f2nb8o$g7v$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org>
Message-ID: <20070520224221.GA1728@panix.com>

On Sat, May 19, 2007, 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.

Excellent work!  This really proves the power of docutils to handle even
complex documents!  Looks pretty good in Lynx, too.

You probably know these, but I don't see anyone else mentioning these
things that need work:

* http://pydoc.gbrandl.de/modules/index.html
needs to reference
http://pydoc.gbrandl.de/reference/functions.html
and 
http://pydoc.gbrandl.de/reference/stdtypes.html
(I see that you've moved them to the Lang Ref, but it will hurt adoption
of this new format if you don't cross-link with the Lib Ref, where they
currently are.)

* Your version creates only a single page for documenting a module; this
is most notable with docs for modules that used to have multiple pages,
such as ``re``.  Compare
http://pydoc.gbrandl.de/modules/re.html
with
http://docs.python.org/lib/module-re.html
There are advantages to the single-page approach, but you should at least
change it to include a top-of-page ToC.
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"Look, it's your affair if you want to play with five people, but don't
go calling it doubles."  --John Cleese anticipates Usenet

From tjreedy at udel.edu  Sun May 20 23:42:49 2007
From: tjreedy at udel.edu (Terry Reedy)
Date: Sun, 20 May 2007 17:42:49 -0400
Subject: [Doc-SIG] The docs, reloaded
References: <f2nb8o$g7v$1@sea.gmane.org>
Message-ID: <f2qfcn$grd$1@sea.gmane.org>

Please add a link to the PEP index (which is also missing from 
docs.python.org, though not from python.org/doc/.

And consider at least some PEPs as part of the corpus indexed (ie, those 
with info not in the regular docs).

tjr




From ndbecker2 at gmail.com  Mon May 21 01:11:12 2007
From: ndbecker2 at gmail.com (Neal Becker)
Date: Sun, 20 May 2007 19:11:12 -0400
Subject: [Doc-SIG] The docs, reloaded
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
Message-ID: <f2qkig$tqf$1@sea.gmane.org>

Georg Brandl wrote:

> Scott Dial schrieb:
>> Neal Becker wrote:
>>> Sounds very interesting.  I just have one concern/question.  I hope that
>>> while moving away from latex, we are not precluding the ability to write
>>> math as part of the documentation.  What would be my choices for add
>>> math
>>> to the documentation?  Hopefully using latex, since there really isn't
>>> AFAIK any other competitor for this.
>>> 
>> 
>> Where in the current documentation is there any math notation /at all/?
>> In all my reading of it, I have not run across anything that appeared
>> like it was being used. Besides that question, is the full power of
>> LaTeX math notation really necessary here? I somehow doubt anything more
>> than simple expressions of runtime performance and container behaviors
>> are appropriate for any documentation we have.
> 
> There is exactly one instance of LaTeX math in the whole docs, it's in the
> description of audioop, AFAIR, an contains a sum over square roots...
> 
> So, that's not really a concern of mine ;)
> 
> Georg
> 

There is an effort as part of numpy to come up with a new system using
docstrings.  It seems to me it would be unfortunate if these two efforts
were not coordinated.


From robert.kern at gmail.com  Mon May 21 02:00:04 2007
From: robert.kern at gmail.com (Robert Kern)
Date: Sun, 20 May 2007 19:00:04 -0500
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <f2qkig$tqf$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org>
	<f2qcds$8b9$1@sea.gmane.org>	<4650B823.4050908@scottdial.com>
	<f2qel6$eeg$1@sea.gmane.org> <f2qkig$tqf$1@sea.gmane.org>
Message-ID: <f2qne6$494$1@sea.gmane.org>

Neal Becker wrote:

> There is an effort as part of numpy to come up with a new system using
> docstrings.  It seems to me it would be unfortunate if these two efforts
> were not coordinated.

I don't think so. The issue with numpy is getting our act together and making
parseable docstrings for auto-generated API documentation using existing tools
or slightly modified versions thereof. No one is actually contemplating building
a new tool. AFAICT, Georg's (excellent) work doesn't address that use. I don't
think there is anything to coordinate, here. Provided that Georg's system
doesn't place too many restrictions on the reST it handles, we could use the
available reST math options if we wanted to use Georg's system.

I'd much rather see Georg spend his time working on the docs for the Python
language and the feature set it requires. If the numpy project needs to extend
that feature set, we'll provide the manpower ourselves.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
 that is made terrible by our own mad attempt to interpret it as though it had
 an underlying truth."
  -- Umberto Eco


From jmg3000 at gmail.com  Mon May 21 02:17:37 2007
From: jmg3000 at gmail.com (John Gabriele)
Date: Sun, 20 May 2007 20:17:37 -0400
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <f2qne6$494$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
	<f2qkig$tqf$1@sea.gmane.org> <f2qne6$494$1@sea.gmane.org>
Message-ID: <65e0bb520705201717w6d2615b1m261df406e89a2cf7@mail.gmail.com>

On 5/20/07, Robert Kern <robert.kern at gmail.com> wrote:
> Neal Becker wrote:
>
> > There is an effort as part of numpy to come up with a new system using
> > docstrings.  It seems to me it would be unfortunate if these two efforts
> > were not coordinated.
>
> I don't think so. The issue with numpy is getting our act together and making
> parseable docstrings for auto-generated API documentation using existing tools
> or slightly modified versions thereof. No one is actually contemplating building
> a new tool.

Actually, I believe Ron Adam is working on that. See his previous
posts regarding his updates to pydoc. He's been asking for folks to
have a look at his code, in fact. :)

---John

From robert.kern at gmail.com  Mon May 21 02:27:35 2007
From: robert.kern at gmail.com (Robert Kern)
Date: Sun, 20 May 2007 19:27:35 -0500
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <65e0bb520705201717w6d2615b1m261df406e89a2cf7@mail.gmail.com>
References: <f2nb8o$g7v$1@sea.gmane.org>
	<f2qcds$8b9$1@sea.gmane.org>	<4650B823.4050908@scottdial.com>
	<f2qel6$eeg$1@sea.gmane.org>	<f2qkig$tqf$1@sea.gmane.org>
	<f2qne6$494$1@sea.gmane.org>
	<65e0bb520705201717w6d2615b1m261df406e89a2cf7@mail.gmail.com>
Message-ID: <f2qp1p$7mt$1@sea.gmane.org>

John Gabriele wrote:
> On 5/20/07, Robert Kern <robert.kern at gmail.com> wrote:
>> Neal Becker wrote:
>>
>>> There is an effort as part of numpy to come up with a new system using
>>> docstrings.  It seems to me it would be unfortunate if these two efforts
>>> were not coordinated.
>> I don't think so. The issue with numpy is getting our act together and making
>> parseable docstrings for auto-generated API documentation using existing tools
>> or slightly modified versions thereof. No one is actually contemplating building
>> a new tool.
> 
> Actually, I believe Ron Adam is working on that. See his previous
> posts regarding his updates to pydoc. He's been asking for folks to
> have a look at his code, in fact. :)

Sorry, I thought the context was clear. "No one [as part of numpy] is actually
...." Better?

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
 that is made terrible by our own mad attempt to interpret it as though it had
 an underlying truth."
  -- Umberto Eco


From skip at pobox.com  Mon May 21 02:07:45 2007
From: skip at pobox.com (skip at pobox.com)
Date: Sun, 20 May 2007 19:07:45 -0500
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <f2qel6$eeg$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
Message-ID: <18000.58065.249249.648413@montanaro.dyndns.org>


    >>> What would be my choices for add math to the documentation?

    >> Where in the current documentation is there any math notation /at
    >> all/?

    Georg> There is exactly one instance of LaTeX math in the whole docs,
    Georg> it's in the description of audioop, AFAIR, an contains a sum over
    Georg> square roots...

    Georg> So, that's not really a concern of mine ;)

You must realize that people will use the core tools to create documentation
for third party packages which aren't in the core.  If you replace LaTeX
with something else I think you need to keep math in mind whether it's used
in the core documentation or not.

Skip

From blais at furius.ca  Mon May 21 04:26:46 2007
From: blais at furius.ca (Martin Blais)
Date: Sun, 20 May 2007 19:26:46 -0700
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <18000.58065.249249.648413@montanaro.dyndns.org>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
	<18000.58065.249249.648413@montanaro.dyndns.org>
Message-ID: <1b151690705201926g750e1e78qc1a71629986e5f22@mail.gmail.com>

On 5/20/07, skip at pobox.com <skip at pobox.com> wrote:
>
>     Georg> There is exactly one instance of LaTeX math in the whole docs,
>     Georg> it's in the description of audioop, AFAIR, an contains a sum over
>     Georg> square roots...
>
>     Georg> So, that's not really a concern of mine ;)
>
> You must realize that people will use the core tools to create documentation
> for third party packages which aren't in the core.  If you replace LaTeX
> with something else I think you need to keep math in mind whether it's used
> in the core documentation or not.

IMHO the question of math support in ReST is one that should be best
answered at the level of docutils, instead of Georg.  A number of
discussions on that topic have already taken place.

From rrr at ronadam.com  Mon May 21 05:28:48 2007
From: rrr at ronadam.com (Ron Adam)
Date: Sun, 20 May 2007 22:28:48 -0500
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <f2qp1p$7mt$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org>	<f2qcds$8b9$1@sea.gmane.org>	<4650B823.4050908@scottdial.com>	<f2qel6$eeg$1@sea.gmane.org>	<f2qkig$tqf$1@sea.gmane.org>	<f2qne6$494$1@sea.gmane.org>	<65e0bb520705201717w6d2615b1m261df406e89a2cf7@mail.gmail.com>
	<f2qp1p$7mt$1@sea.gmane.org>
Message-ID: <465111F0.3070108@ronadam.com>

Robert Kern wrote:
> John Gabriele wrote:
>> On 5/20/07, Robert Kern <robert.kern at gmail.com> wrote:
>>> Neal Becker wrote:
>>>
>>>> There is an effort as part of numpy to come up with a new system using
>>>> docstrings.  It seems to me it would be unfortunate if these two efforts
>>>> were not coordinated.
>>> I don't think so. The issue with numpy is getting our act together and making
>>> parseable docstrings for auto-generated API documentation using existing tools
>>> or slightly modified versions thereof. No one is actually contemplating building
>>> a new tool.
>> Actually, I believe Ron Adam is working on that. See his previous
>> posts regarding his updates to pydoc. He's been asking for folks to
>> have a look at his code, in fact. :)
> 
> Sorry, I thought the context was clear. "No one [as part of numpy] is actually
> ...." Better?
> 

I'm not addressing the actual formatting of the doc strings directly.  But 
I am making it so the doc string from a class or object can be pre or post 
formatted in some way if desired.

I'm going to try to put up some example web pages soon.  They won't be 
quite as impressive as Georg's though.  :-)

Cheers,
    Ron

From skip at pobox.com  Mon May 21 13:01:20 2007
From: skip at pobox.com (skip at pobox.com)
Date: Mon, 21 May 2007 06:01:20 -0500
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <bbaeab100705202224q1b632232y822e61a11027fdbf@mail.gmail.com>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
	<18000.58065.249249.648413@montanaro.dyndns.org>
	<46511FFE.4020803@v.loewis.de>
	<bbaeab100705202224q1b632232y822e61a11027fdbf@mail.gmail.com>
Message-ID: <18001.31744.271598.871237@montanaro.dyndns.org>


    Brett> Martin beat me to my comment.  =) Python's needs should come
    Brett> first, period.  If Georg wants to add math support, fine.  But
    Brett> honestly I would rather he spend his time on Python-specific
    Brett> stuff then get bogged down to support possible third parties.

I think the people who have responded to my comment read too much into it.
Nowhere do I think I asked Georg to write an equation typesetter to include
in the Python documentation toolchain.  I asked that math capability be
considered.  I have no idea what tools he used to build his new
documentation set.  I only briefly glanced at a couple of the output pages.
I think what he has done is marvelous.  However, I don't think the door
should be shut on equation display.  Is there a route to it based on the
tools Georg is using?  If not, then I think some accommodation should be
made.  I'm being vague here on purpose because I'm unfamiliar with the
available tools.  The one thing I do know is that LaTeX provides that today
and by removing it from the toolchain you have removed a significant piece
of functionality.

Skip

From skip at pobox.com  Mon May 21 12:54:36 2007
From: skip at pobox.com (skip at pobox.com)
Date: Mon, 21 May 2007 05:54:36 -0500
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <46511FFE.4020803@v.loewis.de>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
	<18000.58065.249249.648413@montanaro.dyndns.org>
	<46511FFE.4020803@v.loewis.de>
Message-ID: <18001.31340.881646.672542@montanaro.dyndns.org>


    >> You must realize that people will use the core tools to create
    >> documentation for third party packages which aren't in the core.  If
    >> you replace LaTeX with something else I think you need to keep math
    >> in mind whether it's used in the core documentation or not.

    Martin> I disagree. The documentation infrastructure of Python should
    Martin> only consider the needs of Python itself. If other people can
    Martin> use that infrastructure for other purposes, fine - if they find
    Martin> that it does not meet their needs, they have to look elsewhere.

Then I submit that you are probably removing some significant piece of
functionality from the provided documentation toolchain which some people
probably rely on.  After all, that's what LaTeX excels at.  They will be
able to continue to use the old tools, but where will they get them if they
are no longer part of Python?

Skip

From fdrake at acm.org  Mon May 21 15:23:47 2007
From: fdrake at acm.org (Fred L. Drake, Jr.)
Date: Mon, 21 May 2007 09:23:47 -0400
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <18001.31340.881646.672542@montanaro.dyndns.org>
References: <f2nb8o$g7v$1@sea.gmane.org> <46511FFE.4020803@v.loewis.de>
	<18001.31340.881646.672542@montanaro.dyndns.org>
Message-ID: <200705210923.47610.fdrake@acm.org>

On Monday 21 May 2007, skip at pobox.com wrote:
 > Then I submit that you are probably removing some significant piece of
 > functionality from the provided documentation toolchain which some people
 > probably rely on.  After all, that's what LaTeX excels at.  They will be
 > able to continue to use the old tools, but where will they get them if
 > they are no longer part of Python?

I'll be happy to pull the existing tools out into a separate distribution if 
we move to something else for Python.  There are too many users of the 
existing tools to abandon.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>

From g.brandl at gmx.net  Mon May 21 21:49:42 2007
From: g.brandl at gmx.net (Georg Brandl)
Date: Mon, 21 May 2007 21:49:42 +0200
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <20070520224221.GA1728@panix.com>
References: <f2nb8o$g7v$1@sea.gmane.org> <20070520224221.GA1728@panix.com>
Message-ID: <f2st52$l8$1@sea.gmane.org>

Aahz schrieb:
> On Sat, May 19, 2007, 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.
> 
> Excellent work!  This really proves the power of docutils to handle even
> complex documents!  Looks pretty good in Lynx, too.

Thanks! The docutils really do a good job there.

> You probably know these, but I don't see anyone else mentioning these
> things that need work:
> 
> * http://pydoc.gbrandl.de/modules/index.html
> needs to reference
> http://pydoc.gbrandl.de/reference/functions.html
> and 
> http://pydoc.gbrandl.de/reference/stdtypes.html
> (I see that you've moved them to the Lang Ref, but it will hurt adoption
> of this new format if you don't cross-link with the Lib Ref, where they
> currently are.)

I've moved these sections as a suggestion; for me it always felt more natural
this way. However, I intend to ask for opinions there; if the consensus is
that the current order is better, it can be reinstated with a change of one or
two lines in the converter.

But you're right: A link for those being used to the old order is needed
in any case.

> * Your version creates only a single page for documenting a module; this
> is most notable with docs for modules that used to have multiple pages,
> such as ``re``.  Compare
> http://pydoc.gbrandl.de/modules/re.html
> with
> http://docs.python.org/lib/module-re.html
> There are advantages to the single-page approach, but you should at least
> change it to include a top-of-page ToC.

The TOC is there, in the left sidebar.

I agree that multiple pages can be much more readable for large chapters.
That is one thing that would have to be decide after the conversion, and
do manually (which isn't really hard).

cheers,
Georg


From ndbecker2 at gmail.com  Tue May 22 01:41:48 2007
From: ndbecker2 at gmail.com (Neal Becker)
Date: Mon, 21 May 2007 19:41:48 -0400
Subject: [Doc-SIG] The docs, reloaded
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
	<18000.58065.249249.648413@montanaro.dyndns.org>
Message-ID: <f2tans$qum$1@sea.gmane.org>

skip at pobox.com wrote:

> 
>     >>> What would be my choices for add math to the documentation?
> 
>     >> Where in the current documentation is there any math notation /at
>     >> all/?
> 
>     Georg> There is exactly one instance of LaTeX math in the whole docs,
>     Georg> it's in the description of audioop, AFAIR, an contains a sum
>     over Georg> square roots...
> 
>     Georg> So, that's not really a concern of mine ;)
> 
> You must realize that people will use the core tools to create
> documentation
> for third party packages which aren't in the core.  If you replace LaTeX
> with something else I think you need to keep math in mind whether it's
> used in the core documentation or not.
> 
Perhaps my comment was misunderstood.  I have no objection to a new system,
and it does not have to be based on latex.  I just hope there will be some
escape mechanism that allows math.  It happens that for math markup, there
isn't really anything better (or more familiar) than latex.


From aahz at pythoncraft.com  Tue May 22 03:02:34 2007
From: aahz at pythoncraft.com (Aahz)
Date: Mon, 21 May 2007 18:02:34 -0700
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <f2st52$l8$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org> <20070520224221.GA1728@panix.com>
	<f2st52$l8$1@sea.gmane.org>
Message-ID: <20070522010234.GA21664@panix.com>

On Mon, May 21, 2007, Georg Brandl wrote:
> Aahz schrieb:
>> 
>> * Your version creates only a single page for documenting a module; this
>> is most notable with docs for modules that used to have multiple pages,
>> such as ``re``.  Compare
>> http://pydoc.gbrandl.de/modules/re.html
>> with
>> http://docs.python.org/lib/module-re.html
>> There are advantages to the single-page approach, but you should at least
>> change it to include a top-of-page ToC.
> 
> The TOC is there, in the left sidebar.

Gotcha.  That's being done with CSS.  Normally, I don't have a problem
with that, but I think for this work the ToC should go at the top of the
source.
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"Look, it's your affair if you want to play with five people, but don't
go calling it doubles."  --John Cleese anticipates Usenet

From skip at pobox.com  Tue May 22 03:20:08 2007
From: skip at pobox.com (skip at pobox.com)
Date: Mon, 21 May 2007 20:20:08 -0500
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <f2tans$qum$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
	<18000.58065.249249.648413@montanaro.dyndns.org>
	<f2tans$qum$1@sea.gmane.org>
Message-ID: <18002.17736.138574.686866@montanaro.dyndns.org>


    Neal> It happens that for math markup, there isn't really anything
    Neal> better (or more familiar) than latex.

True enough.  There is MathML and its offspring, ASCIIMathML, which are
probably worth looking at.

    http://www.w3.org/Math/
    http://www1.chapman.edu/~jipsen/asciimath.html

I have no idea if either one has backend support for presentation outside
the web, but if people are interested in this (probably within the docutils
scope) they probably should be considered.  ASCIIMathML in particular is
probably worth using now within even if you can't convert it to any other
format.  It's about as readable as LaTeX source.

Skip

From jmg3000 at gmail.com  Tue May 22 06:02:43 2007
From: jmg3000 at gmail.com (John Gabriele)
Date: Tue, 22 May 2007 00:02:43 -0400
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <f2tans$qum$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
	<18000.58065.249249.648413@montanaro.dyndns.org>
	<f2tans$qum$1@sea.gmane.org>
Message-ID: <65e0bb520705212102t7b33b7d6i541d7b2d67b4a216@mail.gmail.com>

On 5/21/07, Neal Becker <ndbecker2 at gmail.com> wrote:
> skip at pobox.com wrote:
>
> >     >>> What would be my choices for add math to the documentation?
> >
> >     >> Where in the current documentation is there any math notation /at
> >     >> all/?
> >
> >     Georg> There is exactly one instance of LaTeX math in the whole docs,
> >     Georg> it's in the description of audioop, AFAIR, an contains a sum
> >     over Georg> square roots...
> >
> >     Georg> So, that's not really a concern of mine ;)
> >
> > You must realize that people will use the core tools to create
> > documentation
> > for third party packages which aren't in the core.  If you replace LaTeX
> > with something else I think you need to keep math in mind whether it's
> > used in the core documentation or not.
> >
> Perhaps my comment was misunderstood.  I have no objection to a new system,
> and it does not have to be based on latex.  I just hope there will be some
> escape mechanism that allows math.  It happens that for math markup, there
> isn't really anything better (or more familiar) than latex.

I'm fairly new to reST, and don't know all the ins and outs of it, but
I'd always just assumed that either there is or there will be a simple
way to escape to TeX math notation. That is, such that when you run
``rst2latex``, your equations will come through unscathed. And when
you run ``rst2html``, well, probably png's will get generated and the
html will just link to them as inline images (of course, you'll need a
TeX implementation installed for that).

Writing equations as done with TeX/LaTeX is so universal and
well-known that even if the docutils folks used some other notation
for mathematics in reST-formatted docs, a way to use TeX-style math
would certainly pop out of the woodwork at some point. There's a lot
of folks out there using LaTeX because they need to put math in their
docs, and don't really have any other workable option.

---John

From ianb at colorstudy.com  Tue May 22 06:08:01 2007
From: ianb at colorstudy.com (Ian Bicking)
Date: Mon, 21 May 2007 23:08:01 -0500
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <65e0bb520705212102t7b33b7d6i541d7b2d67b4a216@mail.gmail.com>
References: <f2nb8o$g7v$1@sea.gmane.org>
	<f2qcds$8b9$1@sea.gmane.org>	<4650B823.4050908@scottdial.com>
	<f2qel6$eeg$1@sea.gmane.org>	<18000.58065.249249.648413@montanaro.dyndns.org>	<f2tans$qum$1@sea.gmane.org>
	<65e0bb520705212102t7b33b7d6i541d7b2d67b4a216@mail.gmail.com>
Message-ID: <46526CA1.2050209@colorstudy.com>

John Gabriele wrote:
> I'm fairly new to reST, and don't know all the ins and outs of it, but
> I'd always just assumed that either there is or there will be a simple
> way to escape to TeX math notation. That is, such that when you run
> ``rst2latex``, your equations will come through unscathed. And when
> you run ``rst2html``, well, probably png's will get generated and the
> html will just link to them as inline images (of course, you'll need a
> TeX implementation installed for that).

You can do something like:

.. raw::: latex
    (expression)

You'll have to provide your html equivalent on your own (with .. raw:: 
html).  A directive could be created that would render a latex 
expression as an image in other contexts; I don't know if one exists. 
It's possible it already does somewhere.

-- 
Ian Bicking | ianb at colorstudy.com | http://blog.ianbicking.org
             | Write code, do good | http://topp.openplans.org/careers

From LeWiemann at gmail.com  Tue May 22 06:41:12 2007
From: LeWiemann at gmail.com (Lea Wiemann)
Date: Tue, 22 May 2007 00:41:12 -0400
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <46526CA1.2050209@colorstudy.com>
References: <f2nb8o$g7v$1@sea.gmane.org>	<f2qcds$8b9$1@sea.gmane.org>	<4650B823.4050908@scottdial.com>	<f2qel6$eeg$1@sea.gmane.org>	<18000.58065.249249.648413@montanaro.dyndns.org>	<f2tans$qum$1@sea.gmane.org>	<65e0bb520705212102t7b33b7d6i541d7b2d67b4a216@mail.gmail.com>
	<46526CA1.2050209@colorstudy.com>
Message-ID: <46527468.8010607@gmail.com>

Ian Bicking wrote:

> A directive could be created that would render a latex
> expression as an image in other contexts;

There's an experimental directive at
<http://docutils.sf.net/sandbox/latex_directive/>.  Be warned though
that it will take quite a while until we have stable, well-working math
support in Docutils.

// Lea

From jensj at fysik.dtu.dk  Tue May 22 10:06:23 2007
From: jensj at fysik.dtu.dk (Jens =?ISO-8859-1?Q?J=F8rgen?= Mortensen)
Date: Tue, 22 May 2007 10:06:23 +0200
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <46526CA1.2050209@colorstudy.com>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
	<18000.58065.249249.648413@montanaro.dyndns.org>
	<f2tans$qum$1@sea.gmane.org>
	<65e0bb520705212102t7b33b7d6i541d7b2d67b4a216@mail.gmail.com>
	<46526CA1.2050209@colorstudy.com>
Message-ID: <1179821183.28730.3.camel@doppler.fysik.dtu.dk>

On Mon, 2007-05-21 at 23:08 -0500, Ian Bicking wrote:
> You'll have to provide your html equivalent on your own (with .. raw:: 
> html).  A directive could be created that would render a latex 
> expression as an image in other contexts; I don't know if one exists. 
> It's possible it already does somewhere.

There's a "latex-math" role and directive in the docutils sandbox:

  http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/jensj/latex_math

It converts LaTeX equations to MathML.

Jens J?rgen



From skip at pobox.com  Tue May 22 13:06:30 2007
From: skip at pobox.com (skip at pobox.com)
Date: Tue, 22 May 2007 06:06:30 -0500
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <65e0bb520705212102t7b33b7d6i541d7b2d67b4a216@mail.gmail.com>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
	<18000.58065.249249.648413@montanaro.dyndns.org>
	<f2tans$qum$1@sea.gmane.org>
	<65e0bb520705212102t7b33b7d6i541d7b2d67b4a216@mail.gmail.com>
Message-ID: <18002.52918.820271.375451@montanaro.dyndns.org>


    John> I'm fairly new to reST, and don't know all the ins and outs of it,
    John> but I'd always just assumed that either there is or there will be
    John> a simple way to escape to TeX math notation. That is, such that
    John> when you run ``rst2latex``, your equations will come through
    John> unscathed. And when you run ``rst2html``, well, probably png's
    John> will get generated and the html will just link to them as inline
    John> images (of course, you'll need a TeX implementation installed for
    John> that).

PNGs would be fairly yucky.  ASCIIMathML or MathML would be much better.

    John> Writing equations as done with TeX/LaTeX is so universal and
    John> well-known that even if the docutils folks used some other
    John> notation for mathematics in reST-formatted docs, a way to use
    John> TeX-style math would certainly pop out of the woodwork at some
    John> point. There's a lot of folks out there using LaTeX because they
    John> need to put math in their docs, and don't really have any other
    John> workable option.

ASCIIMathML offers LaTeX notation as an option.

Skip

From skip at pobox.com  Tue May 22 14:18:12 2007
From: skip at pobox.com (skip at pobox.com)
Date: Tue, 22 May 2007 07:18:12 -0500
Subject: [Doc-SIG] The docs, reloaded
In-Reply-To: <46526CA1.2050209@colorstudy.com>
References: <f2nb8o$g7v$1@sea.gmane.org> <f2qcds$8b9$1@sea.gmane.org>
	<4650B823.4050908@scottdial.com> <f2qel6$eeg$1@sea.gmane.org>
	<18000.58065.249249.648413@montanaro.dyndns.org>
	<f2tans$qum$1@sea.gmane.org>
	<65e0bb520705212102t7b33b7d6i541d7b2d67b4a216@mail.gmail.com>
	<46526CA1.2050209@colorstudy.com>
Message-ID: <18002.57220.327797.795600@montanaro.dyndns.org>


    Ian> You can do something like:

    Ian> .. raw::: latex
    Ian>     (expression)

    Ian> You'll have to provide your html equivalent on your own (with
    Ian> .. raw:: html).  A directive could be created that would render a
    Ian> latex expression as an image in other contexts; I don't know if one
    Ian> exists.  It's possible it already does somewhere.

I did a little googling.  See Jens Mortensen's work in the docutils sandbox:

    http://docutils.sourceforge.net/sandbox/jensj/latex_math/

Skip

From ncoghlan at gmail.com  Tue May 22 16:04:12 2007
From: ncoghlan at gmail.com (Nick Coghlan)
Date: Wed, 23 May 2007 00:04:12 +1000
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <18002.17736.138574.686866@montanaro.dyndns.org>
References: <f2nb8o$g7v$1@sea.gmane.org>
	<f2qcds$8b9$1@sea.gmane.org>	<4650B823.4050908@scottdial.com>
	<f2qel6$eeg$1@sea.gmane.org>	<18000.58065.249249.648413@montanaro.dyndns.org>	<f2tans$qum$1@sea.gmane.org>
	<18002.17736.138574.686866@montanaro.dyndns.org>
Message-ID: <4652F85C.4030904@gmail.com>

skip at pobox.com wrote:
> True enough.  There is MathML and its offspring, ASCIIMathML, which are
> probably worth looking at.
> 
>     http://www.w3.org/Math/
>     http://www1.chapman.edu/~jipsen/asciimath.html
> 
> I have no idea if either one has backend support for presentation outside
> the web,

MathML is the language used for equations in Open Document Format (aka 
ISO 26300). I don't know what extra typesetting tricks (if any) they 
wrap around it, though.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------
             http://www.boredomandlaziness.org

From armin.ronacher at active-4.com  Tue May 22 17:07:00 2007
From: armin.ronacher at active-4.com (Armin Ronacher)
Date: Tue, 22 May 2007 15:07:00 +0000 (UTC)
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
References: <f2nb8o$g7v$1@sea.gmane.org> <20070520224221.GA1728@panix.com>
	<f2st52$l8$1@sea.gmane.org> <20070522010234.GA21664@panix.com>
Message-ID: <loom.20070522T170343-644@post.gmane.org>

Hi,

Aahz <aahz <at> pythoncraft.com> writes:

> Gotcha.  That's being done with CSS.  Normally, I don't have a problem
> with that, but I think for this work the ToC should go at the top of the
> source.

(Somehow my message wasn't posted so here my reply again)

I decided against the toc at the top of the page in the source because if you
visit a page with a larger toc with a browser like links you just see pages of
toc before the actual content is visible. But I would love to add a link to the
top of the page that says "to the toc" which is invisible for css compliant
browsers.

Regards,
Armin


From rrr at ronadam.com  Sat May 26 22:59:04 2007
From: rrr at ronadam.com (Ron Adam)
Date: Sat, 26 May 2007 15:59:04 -0500
Subject: [Doc-SIG] [Python-Dev] The docs, reloaded
In-Reply-To: <f3a2mb$a0p$1@sea.gmane.org>
References: <f2nb8o$g7v$1@sea.gmane.org> <f3a2mb$a0p$1@sea.gmane.org>
Message-ID: <46589F98.2020409@ronadam.com>

Georg Brandl wrote:
> Hi,
> 
> We managed to get an up to date version of the web version of the docs running
> on the server. The address is still the same (http://pydoc.gbrandl.de:3000) and
> it's also still running on top of wsgiref.
> 
> Changes so far:
>    * comments: each page that is generated from an rst file can have some
>      comments attached to it. Commenting doesn't require registration at the
>      moment.
>    * antispam with optional reverse captcha (captcha for bots, a hidden input
>      field named "homepage" which bots hopefully fill out, dumb as they are) and
>      a regular expression filter rules based on MoinMoin's BadContent file.
>    * administration panel for moderating comments. You can find the admin panel
>      at http://pydoc.gbrandl.de:3000/admin/ -- login credentials are
>      testuser:password)
>    * feeds for comments on a page or the last n comments on the whole site.
>    * source view is text only (again).
> 
> What still works:
>    * intelligent error pages: if a page does not exist the URL path is used to
>      conduct a fuzzy keyword search (see below).
>    * fuzzy keyword search: "os.path.exists" jumps to the entry, "os.paht.exists"
>      shows some possibilities.
> 
> What needs to be implemented:
>    * full text search
>    * proposing documentation patches
> 
> Note that the comment area is really, really dark, that's intentional.  This is
> meant to visually separate comments from the official docs, but if the constrast
> is deemed to unsettling, another way can be found.
> 
> Also, we're experimenting with alternate stylesheets, e.g. placing the sidebar
> on the right of the main text, or a "traditional" style for those liking the
> original docs' style.
> 
> In any case, we're waiting for your input!
> 
> cheers,
> Georg and Armin

Yes, the comments are a bit too dark.  The separation could be done better 
by moving it below the footer.  Or better yet, duplicate the navigation bar 
between the the document page and the comments.


   ------------------------------------------------
   crumbs                                navagation
   ------------------------------------------------
     side |    main page
     bar  |
          |
          |
   ------------------------------------------------
   crumbs                                navagation
   ------------------------------------------------
       User Comment section


   ------------------------------------------------
                    copy right
   ------------------------------------------------


The user comment section could have it's own side bar if that's desirable.

Also the python version information needs to be on every page someplace.


Ron

From LeWiemann at gmail.com  Thu May 31 03:38:49 2007
From: LeWiemann at gmail.com (Lea Wiemann)
Date: Thu, 31 May 2007 03:38:49 +0200
Subject: [Doc-SIG] [Pointer] Multi-file input
Message-ID: <465E2729.1040606@gmail.com>

Hi everyone,

I'm starting phase 1 of my Google Summer of Code project (Documenting
Python Packages with Docutils), which is multi-file input for
Docutils/reStructuredText (NB multi-file input, not output).

I'm moving all the discussion to Docutils-develop
(http://docutils.sf.net/docs/user/mailing-lists.html#docutils-develop),
because I don't want to flood Doc-SIG with technical details.  Feel free
to join in!

Best wishes,

    Lea