From amk at amk.ca  Wed Apr  9 03:43:08 2008
From: amk at amk.ca (A.M. Kuchling)
Date: Tue, 8 Apr 2008 21:43:08 -0400
Subject: [Doc-SIG] Reference guide, and images
Message-ID: <20080409014307.GA18179@amk.local>

1) The reference guide occasionally refers to past Python versions,
mentioning that a feature was introduced in such-and-such a version.  
For example, in lexical_analysis.rst:

. [#] In versions of Python prior to 2.4, octal and hexadecimal
   literals in the range just above the largest representable plain
   integer but below the largest unsigned 32-bit number (on a machine
   using 32-bit arithmetic), 4294967296, were taken as the negative
   plain integer obtained by subtracting 4294967296 from their
   unsigned value.

Should the reference guide include this past history, or just describe 
the version of Python it's shipped with?

2) With the shift to HTML and Sphinx, it's probably much easier to include 
images in the docs.  (I'm thinking of reviving the railroad syntax
diagrams.)  What image format would be best?  Bitmaps (PNG/JPG) or
vector (SVG)?

3) In the 'what's new', I have comments recording bug and patch
numbers, because it's useful information for me.  It strikes me
that this information might be interesting to include as part of
the published HTML.  Does that seem like a good idea?  I envision
something very brief; perhaps the text would read "Contributed by 
so-so; <patch #X>.  Can anyone suggest a better rendering?

--amk

From g.brandl at gmx.net  Wed Apr  9 19:39:42 2008
From: g.brandl at gmx.net (Georg Brandl)
Date: Wed, 09 Apr 2008 19:39:42 +0200
Subject: [Doc-SIG] Reference guide, and images
In-Reply-To: <20080409014307.GA18179@amk.local>
References: <20080409014307.GA18179@amk.local>
Message-ID: <47FCFF5E.7070902@gmx.net>

A.M. Kuchling schrieb:
> 1) The reference guide occasionally refers to past Python versions,
> mentioning that a feature was introduced in such-and-such a version.  
> For example, in lexical_analysis.rst:
> 
> .. [#] In versions of Python prior to 2.4, octal and hexadecimal
>    literals in the range just above the largest representable plain
>    integer but below the largest unsigned 32-bit number (on a machine
>    using 32-bit arithmetic), 4294967296, were taken as the negative
>    plain integer obtained by subtracting 4294967296 from their
>    unsigned value.
> 
> Should the reference guide include this past history, or just describe 
> the version of Python it's shipped with?

Personally, I'm fine with these notes within in the 2.x series. For the
3.0, I'd like to remove them, just as we've removed all versionadded/changed
tags.

> 2) With the shift to HTML and Sphinx, it's probably much easier to include 
> images in the docs.  (I'm thinking of reviving the railroad syntax
> diagrams.)  What image format would be best?  Bitmaps (PNG/JPG) or
> vector (SVG)?

PNG would be my choice since it's widely supported and loss-free. SVG
is nice but browser adoption is lousy.

For latex output, PNG works with pdflatex, for postscript I'll have to
whip up a conversion stage.

> 3) In the 'what's new', I have comments recording bug and patch
> numbers, because it's useful information for me.  It strikes me
> that this information might be interesting to include as part of
> the published HTML.  Does that seem like a good idea?  I envision
> something very brief; perhaps the text would read "Contributed by 
> so-so; <patch #X>.  Can anyone suggest a better rendering?

Apart from rendering questions, this is something a custom role can do
nicely:

Contributed by Joe; :issue:`9999`.

I'll add one to the custom Python extensions.

Georg


From g.brandl at gmx.net  Wed Apr  9 20:03:06 2008
From: g.brandl at gmx.net (Georg Brandl)
Date: Wed, 09 Apr 2008 20:03:06 +0200
Subject: [Doc-SIG] Reference guide, and images
In-Reply-To: <47FCFF5E.7070902@gmx.net>
References: <20080409014307.GA18179@amk.local> <47FCFF5E.7070902@gmx.net>
Message-ID: <ftj072$d5$1@ger.gmane.org>

Georg Brandl schrieb:

>> 3) In the 'what's new', I have comments recording bug and patch
>> numbers, because it's useful information for me.  It strikes me
>> that this information might be interesting to include as part of
>> the published HTML.  Does that seem like a good idea?  I envision
>> something very brief; perhaps the text would read "Contributed by 
>> so-so; <patch #X>.  Can anyone suggest a better rendering?
> 
> Apart from rendering questions, this is something a custom role can do
> nicely:
> 
> Contributed by Joe; :issue:`9999`.
> 
> I'll add one to the custom Python extensions.

Okay, there is now an :issue: directive. Currently it only formats to
"issue XXX"; if you like brackets or different formatting let me know.

Georg


From p.f.moore at gmail.com  Thu Apr 10 00:13:56 2008
From: p.f.moore at gmail.com (Paul Moore)
Date: Wed, 9 Apr 2008 23:13:56 +0100
Subject: [Doc-SIG] Reference guide, and images
In-Reply-To: <ftj072$d5$1@ger.gmane.org>
References: <20080409014307.GA18179@amk.local> <47FCFF5E.7070902@gmx.net>
	<ftj072$d5$1@ger.gmane.org>
Message-ID: <79990c6b0804091513p788e2b3chc64a320080feb529@mail.gmail.com>

On 09/04/2008, Georg Brandl <g.brandl at gmx.net> wrote:
> Okay, there is now an :issue: directive. Currently it only formats to
>  "issue XXX"; if you like brackets or different formatting let me know.

In HTML, could it be a link to the bug tracker?
Paul

From g.brandl at gmx.net  Thu Apr 10 00:23:43 2008
From: g.brandl at gmx.net (Georg Brandl)
Date: Thu, 10 Apr 2008 00:23:43 +0200
Subject: [Doc-SIG] Reference guide, and images
In-Reply-To: <79990c6b0804091513p788e2b3chc64a320080feb529@mail.gmail.com>
References: <20080409014307.GA18179@amk.local>
	<47FCFF5E.7070902@gmx.net>	<ftj072$d5$1@ger.gmane.org>
	<79990c6b0804091513p788e2b3chc64a320080feb529@mail.gmail.com>
Message-ID: <ftjffm$qg3$1@ger.gmane.org>

Paul Moore schrieb:
> On 09/04/2008, Georg Brandl <g.brandl at gmx.net> wrote:
>> Okay, there is now an :issue: directive. Currently it only formats to
>>  "issue XXX"; if you like brackets or different formatting let me know.
> 
> In HTML, could it be a link to the bug tracker?

It is already; otherwise the role wouldn't have any advantage over writing
out "issue XXX" ;)

Georg


From p.f.moore at gmail.com  Thu Apr 10 00:52:51 2008
From: p.f.moore at gmail.com (Paul Moore)
Date: Wed, 9 Apr 2008 23:52:51 +0100
Subject: [Doc-SIG] Reference guide, and images
In-Reply-To: <ftjffm$qg3$1@ger.gmane.org>
References: <20080409014307.GA18179@amk.local> <47FCFF5E.7070902@gmx.net>
	<ftj072$d5$1@ger.gmane.org>
	<79990c6b0804091513p788e2b3chc64a320080feb529@mail.gmail.com>
	<ftjffm$qg3$1@ger.gmane.org>
Message-ID: <79990c6b0804091552l6c06b143uc76951765b6486ec@mail.gmail.com>

On 09/04/2008, Georg Brandl <g.brandl at gmx.net> wrote:
>  > In HTML, could it be a link to the bug tracker?
>
> It is already; otherwise the role wouldn't have any advantage over writing
>  out "issue XXX" ;)

Doh. Time for me to get some sleep...

Paul.

From amk at amk.ca  Fri Apr 11 13:52:32 2008
From: amk at amk.ca (A.M. Kuchling)
Date: Fri, 11 Apr 2008 07:52:32 -0400
Subject: [Doc-SIG] Adding third-party links
Message-ID: <20080411115232.GA21277@amk.local>

A long while ago /F had a proposal for an XML format for publishing an
index to documentation so that other packages can incorporate those
links: 

	http://effbot.org/zone/idea-seealso.htm

I've dusted off some old code in sandbox/seealso and updated it, added
a hacked copy of pyspecific.py that adds a :seealsolinks:`module-name`
directive that can be put in the seealso section.  Does this seem
like an idea worth pursuing?

Potential changes: I think the node tree generated by the directive
isn't quite right; the paragraph it returns is wrapped inside another
paragraph.  Should it use Atom rather than a custom XML DTD?  And how
would it be integrated into the build process?  (I'd suggest having a
separate 'make seealso' target that fetched a list of files, parsed
them, and stored them in the build/ directory.)

--amk

From gael.varoquaux at normalesup.org  Sun Apr 13 23:37:25 2008
From: gael.varoquaux at normalesup.org (Gael Varoquaux)
Date: Sun, 13 Apr 2008 23:37:25 +0200
Subject: [Doc-SIG] [Sphinx] An icon/marketting image for the docs
Message-ID: <20080413213725.GV24381@phare.normalesup.org>

Hi,

I know Georg Brandl follows this mailing list, so I would like to make a
feature request for Sphinx.

First of all, thanks a lot for this fantastic tool. I think it will help
a lot improving the quality of the documentation of the different Python
modules.

I would like to display a marketting image for the project I am
documenting. It would be the logo of the project. I think this is good to
give a stronger identity to the project. I know I could do this using the
templating engine, but it means I have to learn it, and this seems such a
common request that I was wondering if it would be possible to add an
option in the default template to have such an image, say in the conf.py.
It could fit very well in the default template.

Cheers,

Ga?l

From ondrej at certik.cz  Mon Apr 14 23:51:32 2008
From: ondrej at certik.cz (Ondrej Certik)
Date: Mon, 14 Apr 2008 23:51:32 +0200
Subject: [Doc-SIG] autogenerating API docs using sphinx
Message-ID: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>

Hi,

I wrote a short script for autogenerating API from sources, the output
are .rst files that sphinx can parse and generate the docs in the
modules/index sections.

Unfortunately, if the docstrings are not written in rst, it's not
going to work properly. Also it uses python inspection (it's easy to
implement), instead of parsing the source files directly.

I am putting it here in case you find it useful. I wrote it for sympy
originally, but we are not using it yet, because the output contains
too much noise.

Please let me know if you improve it/fix it. :)

Ondrej
-------------- next part --------------
A non-text attachment was scrubbed...
Name: generate_reference.py
Type: text/x-python
Size: 4843 bytes
Desc: not available
Url : http://mail.python.org/pipermail/doc-sig/attachments/20080414/fcfef36f/attachment.py 

From gael.varoquaux at normalesup.org  Tue Apr 15 00:20:54 2008
From: gael.varoquaux at normalesup.org (Gael Varoquaux)
Date: Tue, 15 Apr 2008 00:20:54 +0200
Subject: [Doc-SIG] autogenerating API docs using sphinx
In-Reply-To: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>
References: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>
Message-ID: <20080414222054.GD14137@phare.normalesup.org>

On Mon, Apr 14, 2008 at 11:51:32PM +0200, Ondrej Certik wrote:
> I wrote a short script for autogenerating API from sources, the output
> are .rst files that sphinx can parse and generate the docs in the
> modules/index sections.

I just did something similar this week end.

I would like to get it in our SVN, but first Georg needs to implement a
missing directive in the LaTeX writer, because I can't commit my changes
to SVN as long as we can't build PDFs. So to allow people to have a look
at it, I have uploaded the whole documentation directory to
http://gael-varoquaux.info/docs.tar.gz , including the generated rest,
and the html. The two interesting files are render_image.py, which is
kind of pushing the notion of doctests to something with a graphical
output (this is for a 3D plotting application), except that it doesn't
check the output is valid yet, and "mlab_reference", which is an attempt
to make something quite general.

This is very taylored toward the documentation of mlab (a scripting API
for the plotting application). In mlab the docstring are partially
generated automaticaly, with addition of the keyword arguments, so I
could control them well to be good rest. In addition mlab is a namespace
that exposes functions to the users coming from different module, each
giving different fonctionnality. I use this to structure the
documentation.

I am not entirely happy with the code, as there might be to much code
specific to my use. I would like to see some thing like this quite
general, but I also want to keep the high quality output this gives me.
Anybody is welcomed to adapt it to your purposes, while trying to keep it
general, and we can see what comes out of it.

Cheers,

Ga?l

From ondrej at certik.cz  Tue Apr 15 01:34:21 2008
From: ondrej at certik.cz (Ondrej Certik)
Date: Tue, 15 Apr 2008 01:34:21 +0200
Subject: [Doc-SIG] autogenerating API docs using sphinx
In-Reply-To: <20080414222054.GD14137@phare.normalesup.org>
References: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>
	<20080414222054.GD14137@phare.normalesup.org>
Message-ID: <85b5c3130804141634j19180167if38c34b20365d292@mail.gmail.com>

On Tue, Apr 15, 2008 at 12:20 AM, Gael Varoquaux
<gael.varoquaux at normalesup.org> wrote:
> On Mon, Apr 14, 2008 at 11:51:32PM +0200, Ondrej Certik wrote:
>
> > I wrote a short script for autogenerating API from sources, the output
>  > are .rst files that sphinx can parse and generate the docs in the
>  > modules/index sections.
>
>  I just did something similar this week end.
>
>  I would like to get it in our SVN, but first Georg needs to implement a
>
> missing directive in the LaTeX writer, because I can't commit my changes
>  to SVN as long as we can't build PDFs. So to allow people to have a look
>  at it, I have uploaded the whole documentation directory to
>
> http://gael-varoquaux.info/docs.tar.gz , including the generated rest,
>  and the html. The two interesting files are render_image.py, which is
>  kind of pushing the notion of doctests to something with a graphical
>  output (this is for a 3D plotting application), except that it doesn't
>
> check the output is valid yet, and "mlab_reference", which is an attempt
>  to make something quite general.
>
>  This is very taylored toward the documentation of mlab (a scripting API
>  for the plotting application). In mlab the docstring are partially
>
> generated automaticaly, with addition of the keyword arguments, so I
>  could control them well to be good rest. In addition mlab is a namespace
>  that exposes functions to the users coming from different module, each
>  giving different fonctionnality. I use this to structure the
>  documentation.
>
>  I am not entirely happy with the code, as there might be to much code
>  specific to my use. I would like to see some thing like this quite
>  general, but I also want to keep the high quality output this gives me.
>  Anybody is welcomed to adapt it to your purposes, while trying to keep it
>
> general, and we can see what comes out of it.

Thanks Gael for sharing it with us. I looked at it and it looks really great!

I want a code, that goes through all modules (or files) and produces
API doc for each function and each class + methods it finds. When I
have some time, I'll try to look at your code and see if I can reuse
something.

Ondrej

From skip at pobox.com  Tue Apr 15 04:16:34 2008
From: skip at pobox.com (skip at pobox.com)
Date: Mon, 14 Apr 2008 21:16:34 -0500
Subject: [Doc-SIG] autogenerating API docs using sphinx
In-Reply-To: <85b5c3130804141634j19180167if38c34b20365d292@mail.gmail.com>
References: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>
	<20080414222054.GD14137@phare.normalesup.org>
	<85b5c3130804141634j19180167if38c34b20365d292@mail.gmail.com>
Message-ID: <18436.4098.513828.481851@montanaro-dyndns-org.local>


Would it perhaps be better to create a Sphinx backend for an existing
source-to-documentation tool like doxygen?  I have no idea how hard or
feasible that would be or if there are better candidate tools.  Doxygen just
happens to be one I am grudingly familiar with because the C++ programmers
at work use it.  If successful it would have the added benefit of exposing
Sphinx and restructured text outside the Python world.

Skip

From gael.varoquaux at normalesup.org  Tue Apr 15 11:26:21 2008
From: gael.varoquaux at normalesup.org (Gael Varoquaux)
Date: Tue, 15 Apr 2008 11:26:21 +0200
Subject: [Doc-SIG] autogenerating API docs using sphinx
In-Reply-To: <18436.4098.513828.481851@montanaro-dyndns-org.local>
References: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>
	<20080414222054.GD14137@phare.normalesup.org>
	<85b5c3130804141634j19180167if38c34b20365d292@mail.gmail.com>
	<18436.4098.513828.481851@montanaro-dyndns-org.local>
Message-ID: <20080415092621.GD9692@phare.normalesup.org>

On Mon, Apr 14, 2008 at 09:16:34PM -0500, skip at pobox.com wrote:

> Would it perhaps be better to create a Sphinx backend for an existing
> source-to-documentation tool like doxygen?  I have no idea how hard or
> feasible that would be or if there are better candidate tools.  Doxygen just
> happens to be one I am grudingly familiar with because the C++ programmers
> at work use it.  If successful it would have the added benefit of exposing
> Sphinx and restructured text outside the Python world.

That would be great, but it wouldn't replace what I am doing. I have
taylored in my autogeneration of docs a lot of smart guessing (special
cases for my module?) to have a usable and readable doc generated. I hate
the docs generated by tools like doxygen. They are just not meant for end
users, but for programmers.

Two purposes, two tools; fair enough.

Ga?l

From ondrej at certik.cz  Tue Apr 15 11:34:39 2008
From: ondrej at certik.cz (Ondrej Certik)
Date: Tue, 15 Apr 2008 11:34:39 +0200
Subject: [Doc-SIG] autogenerating API docs using sphinx
In-Reply-To: <20080415092621.GD9692@phare.normalesup.org>
References: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>
	<20080414222054.GD14137@phare.normalesup.org>
	<85b5c3130804141634j19180167if38c34b20365d292@mail.gmail.com>
	<18436.4098.513828.481851@montanaro-dyndns-org.local>
	<20080415092621.GD9692@phare.normalesup.org>
Message-ID: <85b5c3130804150234u7c199d33jb9309130706d4e89@mail.gmail.com>

On Tue, Apr 15, 2008 at 11:26 AM, Gael Varoquaux
<gael.varoquaux at normalesup.org> wrote:
>
> On Mon, Apr 14, 2008 at 09:16:34PM -0500, skip at pobox.com wrote:
>
>  > Would it perhaps be better to create a Sphinx backend for an existing
>  > source-to-documentation tool like doxygen?  I have no idea how hard or
>  > feasible that would be or if there are better candidate tools.  Doxygen just
>  > happens to be one I am grudingly familiar with because the C++ programmers
>  > at work use it.  If successful it would have the added benefit of exposing
>  > Sphinx and restructured text outside the Python world.
>
>  That would be great, but it wouldn't replace what I am doing. I have
>  taylored in my autogeneration of docs a lot of smart guessing (special
>  cases for my module?) to have a usable and readable doc generated. I hate
>  the docs generated by tools like doxygen. They are just not meant for end
>  users, but for programmers.
>
>  Two purposes, two tools; fair enough.

Yep. I myself am looking for something that Gael is doing -- simple
API docs for endusers (and myself too!), that quickly shows me, what
kind of stuff I can do. For everything else, I can either use epydoc,
or just look into the sources directly (that's what I prefer).

Ondrej

From ondrej at certik.cz  Fri Apr 18 15:24:26 2008
From: ondrej at certik.cz (Ondrej Certik)
Date: Fri, 18 Apr 2008 15:24:26 +0200
Subject: [Doc-SIG] [Sphinx] An icon/marketting image for the docs
In-Reply-To: <20080413213725.GV24381@phare.normalesup.org>
References: <20080413213725.GV24381@phare.normalesup.org>
Message-ID: <85b5c3130804180624l7a45a843o80661343962af1b3@mail.gmail.com>

On Sun, Apr 13, 2008 at 11:37 PM, Gael Varoquaux
<gael.varoquaux at normalesup.org> wrote:
> Hi,
>
>  I know Georg Brandl follows this mailing list, so I would like to make a
>  feature request for Sphinx.
>
>  First of all, thanks a lot for this fantastic tool. I think it will help
>  a lot improving the quality of the documentation of the different Python
>  modules.
>
>  I would like to display a marketting image for the project I am
>  documenting. It would be the logo of the project. I think this is good to
>  give a stronger identity to the project. I know I could do this using the
>  templating engine, but it means I have to learn it, and this seems such a
>  common request that I was wondering if it would be possible to add an
>  option in the default template to have such an image, say in the conf.py.
>  It could fit very well in the default template.

+1

Ondrej

From g.brandl at gmx.net  Sat Apr 19 23:03:50 2008
From: g.brandl at gmx.net (Georg Brandl)
Date: Sat, 19 Apr 2008 23:03:50 +0200
Subject: [Doc-SIG] [Sphinx] An icon/marketting image for the docs
In-Reply-To: <20080413213725.GV24381@phare.normalesup.org>
References: <20080413213725.GV24381@phare.normalesup.org>
Message-ID: <fudmn1$q43$1@ger.gmane.org>

Gael Varoquaux schrieb:
> Hi,
> 
> I know Georg Brandl follows this mailing list, so I would like to make a
> feature request for Sphinx.
> 
> First of all, thanks a lot for this fantastic tool. I think it will help
> a lot improving the quality of the documentation of the different Python
> modules.
> 
> I would like to display a marketting image for the project I am
> documenting. It would be the logo of the project. I think this is good to
> give a stronger identity to the project. I know I could do this using the
> templating engine, but it means I have to learn it, and this seems such a
> common request that I was wondering if it would be possible to add an
> option in the default template to have such an image, say in the conf.py.
> It could fit very well in the default template.

This is a good idea. Do you have a suggestion where to put the logo in the
templates?

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 g.brandl at gmx.net  Sun Apr 20 11:47:53 2008
From: g.brandl at gmx.net (Georg Brandl)
Date: Sun, 20 Apr 2008 11:47:53 +0200
Subject: [Doc-SIG] autogenerating API docs using sphinx
In-Reply-To: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>
References: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>
Message-ID: <fuf3fl$pb0$1@ger.gmane.org>

Ondrej Certik schrieb:
> Hi,
> 
> I wrote a short script for autogenerating API from sources, the output
> are .rst files that sphinx can parse and generate the docs in the
> modules/index sections.
> 
> Unfortunately, if the docstrings are not written in rst, it's not
> going to work properly. Also it uses python inspection (it's easy to
> implement), instead of parsing the source files directly.
> 
> I am putting it here in case you find it useful. I wrote it for sympy
> originally, but we are not using it yet, because the output contains
> too much noise.
> 
> Please let me know if you improve it/fix it. :)

What does it do differently from autodoc, and could autodoc be extended
to cover your usecase as well?

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  Tue Apr 22 00:03:41 2008
From: gael.varoquaux at normalesup.org (Gael Varoquaux)
Date: Tue, 22 Apr 2008 00:03:41 +0200
Subject: [Doc-SIG] [Sphinx] An icon/marketting image for the docs
In-Reply-To: <fudmn1$q43$1@ger.gmane.org>
References: <20080413213725.GV24381@phare.normalesup.org>
	<fudmn1$q43$1@ger.gmane.org>
Message-ID: <20080421220341.GC2697@phare.normalesup.org>

On Sat, Apr 19, 2008 at 11:03:50PM +0200, Georg Brandl wrote:
> > I would like to display a marketting image for the project I am
> > documenting. It would be the logo of the project. I think this is good to
> > give a stronger identity to the project. I know I could do this using the
> > templating engine, but it means I have to learn it, and this seems such a
> > common request that I was wondering if it would be possible to add an
> > option in the default template to have such an image, say in the conf.py.
> > It could fit very well in the default template.

> This is a good idea. Do you have a suggestion where to put the logo in the
> templates?

I am not sure what you mean. If you mean physically on the default page,
I would see it on top of the side panel, above the table of contents.

Cheers,

Ga?l

From ondrej at certik.cz  Wed Apr 23 01:56:12 2008
From: ondrej at certik.cz (Ondrej Certik)
Date: Wed, 23 Apr 2008 01:56:12 +0200
Subject: [Doc-SIG] autogenerating API docs using sphinx
In-Reply-To: <fuf3fl$pb0$1@ger.gmane.org>
References: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>
	<fuf3fl$pb0$1@ger.gmane.org>
Message-ID: <85b5c3130804221656m4043a0e0reba6163f3afa1da3@mail.gmail.com>

On Sun, Apr 20, 2008 at 11:47 AM, Georg Brandl <g.brandl at gmx.net> wrote:
> Ondrej Certik schrieb:
>
>
> > Hi,
>  >
>  > I wrote a short script for autogenerating API from sources, the output
>  > are .rst files that sphinx can parse and generate the docs in the
>  > modules/index sections.
>  >
>  > Unfortunately, if the docstrings are not written in rst, it's not
>  > going to work properly. Also it uses python inspection (it's easy to
>  > implement), instead of parsing the source files directly.
>  >
>  > I am putting it here in case you find it useful. I wrote it for sympy
>  > originally, but we are not using it yet, because the output contains
>  > too much noise.
>  >
>  > Please let me know if you improve it/fix it. :)
>
>  What does it do differently from autodoc, and could autodoc be extended
>  to cover your usecase as well?

You mean autodoc in sphinx?

I want to get a documentation of all classes+methods and functions in
all files in sympy automatically (we have a lot of .py files and I
don't want to handle each of them manually). I didn't figure it out
how this could be done in autodoc. But if you look at my script, it's
really simple, so the autodoc definitely can be extended.

But the script currently produces quite a lot of noise (some empty
classes, etc.) in the output. It needs to be improved.

Ondrej

From g.brandl at gmx.net  Sun Apr 27 22:04:39 2008
From: g.brandl at gmx.net (Georg Brandl)
Date: Sun, 27 Apr 2008 22:04:39 +0200
Subject: [Doc-SIG] autogenerating API docs using sphinx
In-Reply-To: <85b5c3130804221656m4043a0e0reba6163f3afa1da3@mail.gmail.com>
References: <85b5c3130804141451s478c57b0m24f0eb6779dd5440@mail.gmail.com>	<fuf3fl$pb0$1@ger.gmane.org>
	<85b5c3130804221656m4043a0e0reba6163f3afa1da3@mail.gmail.com>
Message-ID: <fv2m83$f6n$1@ger.gmane.org>

Ondrej Certik schrieb:
> On Sun, Apr 20, 2008 at 11:47 AM, Georg Brandl <g.brandl at gmx.net> wrote:
>> Ondrej Certik schrieb:
>>
>>
>> > Hi,
>>  >
>>  > I wrote a short script for autogenerating API from sources, the output
>>  > are .rst files that sphinx can parse and generate the docs in the
>>  > modules/index sections.
>>  >
>>  > Unfortunately, if the docstrings are not written in rst, it's not
>>  > going to work properly. Also it uses python inspection (it's easy to
>>  > implement), instead of parsing the source files directly.
>>  >
>>  > I am putting it here in case you find it useful. I wrote it for sympy
>>  > originally, but we are not using it yet, because the output contains
>>  > too much noise.
>>  >
>>  > Please let me know if you improve it/fix it. :)
>>
>>  What does it do differently from autodoc, and could autodoc be extended
>>  to cover your usecase as well?
> 
> You mean autodoc in sphinx?

Yes.

> I want to get a documentation of all classes+methods and functions in
> all files in sympy automatically (we have a lot of .py files and I
> don't want to handle each of them manually). I didn't figure it out
> how this could be done in autodoc. But if you look at my script, it's
> really simple, so the autodoc definitely can be extended.
> 
> But the script currently produces quite a lot of noise (some empty
> classes, etc.) in the output. It needs to be improved.

autodoc needs currently at least one entry per module in some file.
It does everything else your script does, as far as I can see.

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 skip at pobox.com  Mon Apr 28 00:16:12 2008
From: skip at pobox.com (skip at pobox.com)
Date: Sun, 27 Apr 2008 17:16:12 -0500
Subject: [Doc-SIG] Double specification of function signatures?
Message-ID: <18452.64300.579813.77697@montanaro-dyndns-org.local>

While cleaning up the documentation for the tempfile module I noticed that
the docstrings for the mk*temp functions in the module itself list their
signatures (incompletely) in the first line.  I don't know if that was
intentional, but it seems both redundant and error-prone to me.  The help()
function already displays the signatures of Python functions.  There's no
need to put them in docstrings and risk having them out-of-date.  For
example:

    >>> help(tempfile.mkdtemp)
    Help on function mkdtemp in module tempfile:

    mkdtemp(suffix='', prefix='tmp', dir=None)
        mkdtemp([suffix, [prefix, [dir]]])
        User-callable function to create and return a unique temporary
        directory.  The return value is the pathname of the directory.

Am I way off-base here?  Let me know, as I have a couple minor tweaks to
check in besides these.

Thx,

Skip

From fuzzyman at voidspace.org.uk  Mon Apr 28 00:26:29 2008
From: fuzzyman at voidspace.org.uk (Michael Foord)
Date: Sun, 27 Apr 2008 23:26:29 +0100
Subject: [Doc-SIG] Double specification of function signatures?
In-Reply-To: <18452.64300.579813.77697@montanaro-dyndns-org.local>
References: <18452.64300.579813.77697@montanaro-dyndns-org.local>
Message-ID: <4814FD95.2010206@voidspace.org.uk>

skip at pobox.com wrote:
> While cleaning up the documentation for the tempfile module I noticed that
> the docstrings for the mk*temp functions in the module itself list their
> signatures (incompletely) in the first line.  I don't know if that was
> intentional, but it seems both redundant and error-prone to me.  The help()
> function already displays the signatures of Python functions.  There's no
> need to put them in docstrings and risk having them out-of-date.  For
> example:
>
>     >>> help(tempfile.mkdtemp)
>     Help on function mkdtemp in module tempfile:
>
>     mkdtemp(suffix='', prefix='tmp', dir=None)
>         mkdtemp([suffix, [prefix, [dir]]])
>         User-callable function to create and return a unique temporary
>         directory.  The return value is the pathname of the directory.
>
> Am I way off-base here?  Let me know, as I have a couple minor tweaks to
> check in besides these.
>   

It seems that any documentation or help tool worth its salt should fetch 
the parameters from the definition and so including them in the 
docstring should be redundant duplication.

Michael Foord

> Thx,
>
> Skip
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG at python.org
> http://mail.python.org/mailman/listinfo/doc-sig
>   


From skip at pobox.com  Mon Apr 28 00:29:33 2008
From: skip at pobox.com (skip at pobox.com)
Date: Sun, 27 Apr 2008 17:29:33 -0500
Subject: [Doc-SIG] Double specification of function signatures?
In-Reply-To: <4814FD95.2010206@voidspace.org.uk>
References: <18452.64300.579813.77697@montanaro-dyndns-org.local>
	<4814FD95.2010206@voidspace.org.uk>
Message-ID: <18452.65101.202393.473799@montanaro-dyndns-org.local>


    Michael> It seems that any documentation or help tool worth its salt
    Michael> should fetch the parameters from the definition and so
    Michael> including them in the docstring should be redundant
    Michael> duplication.

That's my position as well.  Currently we have no way to extract the
function signatures from C code on-the-fly or in a preprocessing step (might
be a good GSoC project), but for functions written in Python I'm of the
opinion the docstrings should not include function signatures.

Skip

From skip at pobox.com  Mon Apr 28 05:06:06 2008
From: skip at pobox.com (skip at pobox.com)
Date: Sun, 27 Apr 2008 22:06:06 -0500
Subject: [Doc-SIG] [Python-Dev] Double specification of function
 signatures?
In-Reply-To: <bbaeab100804271531x1aeae74eic32a930bc43dcbfd@mail.gmail.com>
References: <18452.64300.579813.77697@montanaro-dyndns-org.local>
	<4814FD95.2010206@voidspace.org.uk>
	<18452.65101.202393.473799@montanaro-dyndns-org.local>
	<bbaeab100804271531x1aeae74eic32a930bc43dcbfd@mail.gmail.com>
Message-ID: <18453.16158.25027.879421@montanaro-dyndns-org.local>


    Brett> They shouldn't. Maybe the tempfile module came from a third-party
    Brett> that had some internal doc rule of mentioning the call signature.
    Brett> Regardless, just rip it out.

Done.

Skip