The docs, reloaded

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

Re: [Python-Dev] The docs, reloaded

Martin Blais-2
On 5/20/07, [hidden email] <[hidden email]> 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.
_______________________________________________
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

Ron Adam
In reply to this post by Robert Kern-2
Robert Kern wrote:

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

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
_______________________________________________
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 Skip Montanaro-3

    >> 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
_______________________________________________
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 Skip Montanaro-3

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

Fred Drake-3
In reply to this post by Skip Montanaro-3
On Monday 21 May 2007, [hidden email] 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>
_______________________________________________
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

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

_______________________________________________
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 Skip Montanaro-3
[hidden email] 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.

_______________________________________________
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 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 ([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: [Python-Dev] The docs, reloaded

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

    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
_______________________________________________
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 Neal Becker
On 5/21/07, Neal Becker <[hidden email]> wrote:

> [hidden email] 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
_______________________________________________
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

ianb
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 | [hidden email] | http://blog.ianbicking.org
             | Write code, do good | http://topp.openplans.org/careers
_______________________________________________
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
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
_______________________________________________
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

Jens Jørgen Mortensen
In reply to this post by ianb
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


_______________________________________________
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

Skip Montanaro-3
In reply to this post by John Gabriele

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

Skip Montanaro-3
In reply to this post by ianb

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

Nick Coghlan
In reply to this post by Skip Montanaro-3
[hidden email] 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   |   [hidden email]   |   Brisbane, Australia
---------------------------------------------------------------
             http://www.boredomandlaziness.org
_______________________________________________
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

Armin Ronacher
In reply to this post by Aahz
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

_______________________________________________
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,
>
> 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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
12