The docs, reloaded

classic Classic list List threaded Threaded
38 messages Options
12
Reply | Threaded
Open this post in threaded view
|

The docs, reloaded

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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] The docs, reloaded

Michael Foord-5
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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: The docs, reloaded

John Gabriele
In reply to this post by Georg Brandl-2
On 5/19/07, Georg Brandl <[hidden email]> 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. :)
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: The docs, reloaded

Lea Wiemann
In reply to this post by Georg Brandl-2
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 ([hidden email]),
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
>
>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] The docs, reloaded

Ron Adam
In reply to this post by Georg Brandl-2
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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] The docs, reloaded

Laura Creighton-2
In reply to this post by Michael Foord-5
Wow.  Nice job.  Thank you so very much.

Laura
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] The docs, reloaded

Martin Blais-2
In reply to this post by Georg Brandl-2
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 <[hidden email]> 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
> [hidden email]
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/blais%40furius.ca
>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: The docs, reloaded

Georg Brandl-2
In reply to this post by Georg Brandl-2
[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 <[hidden email]>.

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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] The docs, reloaded

Gael Varoquaux
In reply to this post by Ron Adam
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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: The docs, reloaded

Lea Wiemann
In reply to this post by Georg Brandl-2
[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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] The docs, reloaded

engelbert gruber
In reply to this post by Martin Blais-2
> 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

--

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] The docs, reloaded

Martin Blais-2
In reply to this post by Georg Brandl-2
On 5/20/07, Georg Brandl <[hidden email]> 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!
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: The docs, reloaded

Neal Becker
In reply to this post by Georg Brandl-2
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.

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: The docs, reloaded

Terry Reedy
In reply to this post by Georg Brandl-2
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



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] The docs, reloaded

Aahz
In reply to this post by Georg Brandl-2
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 ([hidden email])           <*>         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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: The docs, reloaded

Neal Becker
In reply to this post by Neal Becker
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.

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: The docs, reloaded

Robert Kern-2
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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] The docs, reloaded

Skip Montanaro-3
In reply to this post by Neal Becker

    >>> 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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: The docs, reloaded

John Gabriele
In reply to this post by Robert Kern-2
On 5/20/07, Robert Kern <[hidden email]> 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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: The docs, reloaded

Robert Kern-2
John Gabriele wrote:

> On 5/20/07, Robert Kern <[hidden email]> 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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
12