Mailman 3 May 2005 - Doc-SIG

Python docs in reST
by Kenneth McDonald May 27, 2005

May 27, 2005

On 5/16/05, doc-sig-request(a)python.org <doc-sig-request(a)python.org> wrote: > Send Doc-SIG mailing list submissions to > doc-sig(a)python.org > > To subscribe or unsubscribe via the World Wide Web, visit > http://mail.python.org/mailman/listinfo/doc-sig > or, via email, send a message with subject or body 'help' to > doc-sig-request(a)python.org > > You can reach the person managing the list at > doc-sig-owner(a)python.org > > When replying, please edit your Subject line so it is more specific > than "Re: Contents of Doc-SIG digest..." > > > Today's Topics: > > 1. Python docs in reST? (Skip Montanaro) > 2. Re: Python docs in reST? (Michael Foord) > To me, the biggest single problem in Python documentation is that there is no standard inline documentation format which has been "blessed" as _the_ standard by the Python core development team. I like Python much better than Ruby, but take a look at Ruby for a an example of what kind of tools can be built once people have a standard as a base. rubydoc is really, really nice Whatever might be chosen or developed, we need IMHO a doc standard that is part of the core python package, and comes with all of the tools needed to use it. Without this, documentation of python modules is always going to be rather ad hoc. Not that this was useful, but in any case if anyone wants to work towards it... :-) Ken

13 60

Re: [Doc-SIG] Python docs in reST?
by Torsten Bronger May 27, 2005

May 27, 2005

Hallöchen! Bill Janssen <janssen(a)parc.com> writes: >> LaTeX seems to be a we-want-to-get-rid-of-it, and reST is still not >> really ready. > > I decided to do the documentation for my latest project, UpLib, in > reST, to see how well it works. My conclusion is that it probably > will never be ready to document Python, because the design goal of > making the reST source read like text conflicts with the goal of > making it functional enough to document a large system. I'm not so pessimistic. I think that only a few constructs are missing to make it suitable for large projects (inclusion and interlinks). But apparently this is already being tackled. For non-Python user guides I use Texinfo. What I really miss is Texinfo's @deffn for explaining functions etc. Yes, I know <http://docutils.sourceforge.net/docs/dev/semantics.html>, but it doesn't solve this issue. reST lacks a standard means of defining function/method signatures, return values, exceptions etc. (Similar structures are needed for classes.) I use field lists at the moment. That's okay, but it's not real logical markup since the reST interpreter has no chance to recognise it as a function definition. Besides, its pdf and HTML results are poor. Other missing things include standardised meta info, i18n (including encodings), formulae (a well-defined subset of LaTeX would be good), and a meta standard for how to use "interpreted text". > [...] > > [...] but next time I'll probably use a simple text markup > language like troff with an appropriate macro package, or better > yet runoff. Do you really think that troff is suitable for large, modern documentation? How many people would have to learn it? How easy is it to install it on Windows? How good are the PDFs generated from it? How is it converted to HTML? (I don't know troff very well, as you can see. ;) Tschö, Torsten. -- Torsten Bronger, aquisgrana, europa vetus

3 7

paste.docsupport (was: Python docs in reST)
by Ian Bicking May 27, 2005

May 27, 2005

(I thought I'd reply back on-list, since this is still about documentation) Michael Foord wrote: > I've had a *quick* look at the paste docsupport. The output looks nice - > but the code looks tied to the paste framework. > > I have a couple of questions I hope you don't mind (I'm considering > implementing something myself - but don't want to duplicate something > you'd do better :-). > > Is your docsupport *specific* to paste - or *could* it work with other > modules ? Right now there's no separation of modules for the Paste and generic code, but the objects are fairly partitioned between the two. There are some Paste-specific DocItem subclasses in docsupport.metadata; it's my expectation that any framework will require domain-specific metadata, and stuff like WSGIKey are examples of that. There's also one custom extractor (HTTPExtractor). > Does it produce standalone references for modules ? Could it be hacked > to support pulling out *specific* docstrings ? (I'd like to code a > convention in my reST docs - that allows for the referencing of specific > docstrings. That way I can produce documentation around my docstrings > rather than have my docstrings *as* documentation - if you see the > difference). Right now you run the extract.py module and pass in a package or module name. It creates a single document right now, but I'd definitely like to make it create a tree of files in the future, and probably automatically create a file that includes from that tree as well, as a kind of minimal fully-automated reference doc -- but you could include those same files into other documents as well. From there it would be really nice to have a link from the including document (with the docstring in isolation) to the larger reference document (that was organized by module), and from there to the actual source (maybe a highlighted source with lots of id tags). That would be neat. > Does it use any conventions in the docstrings to produce the output - or > does it just take the function (class, method etc) name and parameters > and docstrings - with no additional processing ? Right now there's no additional processing. If you look in docsupport.extract there's individual classes to create the formatting of different types of objects. E.g., MethodExtractor (which should probably be named FunctionExtractor) does the functions. You could register different implementations, or subclass the ones that are there. And actually though the docstring is treated like an opaque item currently, extractors look at other things. For example, you can do:: def blah(self, *args, **kw): ... return self.wrapped(*args, **kw) blah.proxy = 'wrapped' And the signature in the docs should match the signature for wrapped. wsgilib.interactive is an example of this. The attribute 'returns' is also searched for a return type -- well, actually just any documentable object (or string reference to an object) which gets inlined in the docs. Right now I'm not doing any real inspection of the docstrings; I haven't felt the need yet, and I'm not sure what distinctions I'll need to make. But at some point I'm sure it will be necessary. Most of the annotation so far has gone into more transparent structures, like attributes. -- Ian Bicking / ianb(a)colorstudy.com / http://blog.ianbicking.org

1 0

[ANN] Docutils 0.3.9 released
by Felix Wiemann May 26, 2005

May 26, 2005

Docutils 0.3.9 Released ======================= Docutils 0.3.9 has been released. You can download it from <http://prdownloads.sf.net/docutils/docutils-0.3.9.tar.gz?download>. The Docutils homepage is located at <http://docutils.sf.net/>. Major Changes Since Docutils 0.3.7 ================================== * Added "file_insertion_enabled" and "raw_enabled" settings. See <http://docutils.sf.net/docs/user/config.html#file-insertion-enabled>. * Added auto-enumerated lists. See <http://docutils.sf.net/docs/ref/rst/restructuredtext.html#enumerated-lists>. * Added "header" and "footer" directives. See <http://docutils.sf.net/docs/ref/rst/directives.html#document-header-footer>. * Added "list-table" directive. See <http://docutils.sf.net/docs/ref/rst/directives.html#list-table>. * Added support for section subtitles. See <http://docutils.sf.net/docs/user/config.html#sectsubtitle-xform>. * Added "field_name_limit" and "option_limit" settings to HTML writer. See <http://docutils.sf.net/docs/user/config.html#field-name-limit>. * Added "cloak_email_addresses" setting to HTML writer. See <http://docutils.sf.net/docs/user/config.html#cloak-email-addresses>. * UTF-8 BOMs are now removed from the input stream. * Many minor improvements and bug fixes. See <http://docutils.sf.net/HISTORY.html#release-0-3-9-2005-05-26>. -- Felix Wiemann -- http://www.ososo.de/

1 0

Python docs in reST?
by Skip Montanaro May 25, 2005

May 25, 2005

A thread on c.l.py ("Python Documentation (should be better?)") got me to thinking about options for improving/restructuring the online documentation. That led me to thinking about converting the current docs to reST. A scan of the last year's worth of list archives didn't yield any obvious discussion on the topic, but I find it hard to believe the topic hasn't been discussed in the past. Pointers to past threads cheerfully accepted. It seems to me that converting to reST has a couple obvious benefits: * dump latex2html * better potential HTML generation options (like HTML w/ an integrated annotation capability) * possibly enlarge pool of documentation contributors Fred wrote some Latex->ESIS->SGML tools that look like they might possibly be redirected to the more-or-less one-time task of converting to reST. Thoughts? -- Skip Montanaro skip(a)pobox.com

9 22

nroff/troff
by Kenneth McDonald May 19, 2005

May 19, 2005

I haven't used these systems in quite a while so I don't know what state they are in, but I still like the way they did things far better than any other system I've seen. Much, much easier to learn than LaTeX, but still very capable. Just wanted to comment. Come to think of it, they might make a decent markup language for incode documentation too. And they really are easy to learn, at least to get off the ground with. Cheers, Ken > ---------- Forwarded message ---------- > From: Bill Janssen <janssen(a)parc.xerox.com> > To: Torsten Bronger <bronger(a)physik.rwth-aachen.de> > Date: Thu, 19 May 2005 15:58:50 PDT > Subject: Re: [Doc-SIG] Python docs in reST? > > Do you really think that troff is suitable for large, modern > > documentation? > > Yes. Entire operating systems have been documented with it. In > addition, the excellent GNU Troff (groff) system by James Clark and a > host of others will produce Postscript or HTML output, among other > formats. > > But I like even simpler systems, such as runoff or roff. >

2 1

two subjects: docutils for python docs, and integrating documentation in source code
by Martin Blais May 19, 2005

May 19, 2005

hi after some fiddling this morning, i'm getting all worked up over some things i feel are missing w.r.t. the python documentation. 1. writing python documentation using docutils, is it possible? here's a cool idea, i don't know if it's been discussed here before, but do you think it would be possible to add docutils directives for all the markup that the python documentation requires? ( in particular, there could be directives to automatically extract much of the information from the python declaratoins themselves, using inspection ) e.g. .. funcdesc:: foo( param1, param2=True ) would automatically parse the function declaration and generate appropriate output. a sort of specialized rest input (just some directives really) with specialise latex output. we could even output using the current LaTeX macros that the python docs are currently using... which brings me to the second issue 2. unifying source code and readable documentation have fiddle with the python documentatoin sources recently, i find it really hard to accept that the docs are separate from the source code. the docs are great, mind you, but having two sources to synchronize just doesn't make sense (amazingly, the docs seem to be pretty accurate, fred is doing an amazing job at monitoring source code changes i guess). it seems to me that auto-generated documentation tools should really be part of python. now, in that regards, one has to recognize that we currently have two types of documentation: a. reference docs, which can be auto-generated with pydoc b. manual docs, which are written in LaTeX could we unite both in some way? this would be really useful for the code i write. one source, for code, and docs. we might want to do something to couple the source code and the written manual, e.g. where we could have a template that outlines the "manual" versoin of the documentation, and our directive would go fetch the docstring for the function or class and insert it inline in our document automatically. a class documentation could look like this: intro and example text .. classdescref:: module.classname ..methoddescref:: module.classname.foo1 ..methoddescref:: module.classname.foo2 ..methoddescref:: module.classname.foo3 ..methoddescref:: module.classname.foo4 this would allow arbitraty ordering of the methods (something which an automated source to docs tool couldn't do) which is required to make docs cleaner, and just fetching parts of the docstring, i.e. some code shouldn't be reflected in user documentation. looking at the current python docs, it seems to me a bit difficult that the source files are entirely separate from the source code. also, one thing that i can't see is how to generate index entries from docutils. also, for typed references e.g. \function{foo}, i don't know how you would do that in docutils. anyway, that's a bit of a quick trigger email, maybe i should do more due diligence to find out if that's been considered in the past... is there some info somewhere about people trying to write the docs of Python using docutils? (and i'm not refering to pysource, rather to convert the Python-<ver>/Docs directory)

6 16

Re: [Doc-SIG] Python docs in reST
by Martin Blais May 18, 2005

May 18, 2005

> >>If I am writing a small (ish) module I can fulfill 1 and 2 with a decent > >>module docstring and proper docstrings for functions and classes etc. In > >>which case I *need* to be able to auto extract the docs and create a > >>reference doc from them. > >> > >>I *do not* want private methods visible in this documentation - and I do > >>want a way of specifying that a function/method should not be included. > >> > >>If the 'user' is a programmer, I don't think there is necessarily a > >>clear distinction between 1 and 2. > >> > >> > > > >well, i would argue that what you want to do is (1), > > > Yes :-) > > > but you want it > >in the source file. > > > > > Yes, and be able to generate an API doc from it. > > >i was suggesting earlier that this could be implemented by adding a > >special docstring of your choice (e.g. __manual__) to your source > >code, it could even be at the end if you want it to. whatever tool > >you use to generate documentation would first extract that flie before > >processing. > > > > > > > > > Why not just use the module docstring ? can you imagine scrolling past an entire manual everytime you open a new file? (i'm assuming we're writing real user documentation in that docstring, not just an overview)

4 4

Current 'standard' documentation generation program/standards for Python?
by Kenneth McDonald May 14, 2005

May 14, 2005

Is there yet an agreed-upon standard (format and/or doc generation prog) for Python documentation? I used epydoc a while back and it was OK, but still not great. Python is by far my fav. language, but the lack of a good doc solution is just driving me nuts! Thanks, Ken

2 1

"inverse" documentation generation
by Vicki Brown May 12, 2005

May 12, 2005

And now for something (perhaps) completely diifferent. Most "documentation generators" are optimized for someone working _on_ the code rather than _with_ the code. That is, they work from the assumption that you have a method/class/module and want to know how it works - not from the view that you know what you want to do and want to discover the best method/class/module that will let you accomplish your goal in the least amount of time and effort :) I want to be able to generate documentation that aids a client in using a set of Python modules, not in implementing and maintaining those modules. Example: Bob is using an automated test framework written in Python. He's writing a test and he'd like to call a routine that will "be like hitting return over and over until it gets me back out to the top of my test." He asks John (one of the framework authors) who says: "We've got that; it's called restart". Bob then hunts through the pydoc documentation for the 100 modules and packages in the framework, then resorts to a find command on the source tree (searching for for "def restart"), and eventually discovers 5 different "restart" methods scattered throughout the code. Back in pydooc, he sees that one of these has a docstring that looks like "the right one". """ restart(): Resets the session to a base state, ready for more method calls. """ The rest appear to be internal methods, not API at all. If John wasn't available, how would Bob ever discover this method? He doesn't know its name. He doesn't know which class or module it's in. He doesn't want to read through pages of pydoc HTML files or familiarize himself with the entire framework code base. He wants to _write a test_. Even if he started with a"find" on the source tree (or a search through the HTML-ized docs), he may not pick the right keywords for the search. I need a way to enhance Bob's efficiency as a client of the framework, not a developer of the framework. At the very least, I think what I want is a way to extract the method, class, and module names, and their docstrings, and present them in an inverse presentation format: instead of digging down through module to class to method, I want to start from the docstrings. I want to start from the viewpoint of "I know what I want to do. Now tell me how to do it". Comments, suggestions, ideas, and general discussion welcomed. -- - V. Vicki Brown <vlb(a)ironport.com> * Internal Technical Documentation http://home.ironport.com/~vlbrown * Jabber: vlbrown(a)ironport.com * Words are, of course, the most powerful drug used by mankind. * -- Rudyard Kipling

1 0