Mailman 3 April 2008 - Doc-SIG

Re: [Doc-SIG] [Python-Dev] Double specification of function signatures?
by skip＠pobox.com April 28, 2008

April 28, 2008

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

1 0

Double specification of function signatures?
by skip＠pobox.com April 27, 2008

April 27, 2008

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

2 2

autogenerating API docs using sphinx
by Ondrej Certik April 27, 2008

April 27, 2008

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

4 8

[Sphinx] An icon/marketting image for the docs
by Gael Varoquaux April 21, 2008

April 21, 2008

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

3 3

Adding third-party links
by A.M. Kuchling April 11, 2008

April 11, 2008

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

1 0

Reference guide, and images
by A.M. Kuchling April 9, 2008

April 9, 2008

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

3 5