From goodger at python.org Fri Apr 8 05:51:04 2005 From: goodger at python.org (David Goodger) Date: Fri Apr 8 05:51:20 2005 Subject: [Doc-SIG] "header" & "footer" directives added Message-ID: <4255FFA8.5040609@python.org> in "Re: A more flexible RST -> HTML writer?" on Docutils-users, I wrote: > The direct, correct solution is to have a mechanism to specify > "header" content (content to appear before the doc title). > I am working on such a mechanism. Work complete. I have implemented two new directives: "header" and "footer", with HTML support. The "header" directive adds the directive contents to the document header, which is rendered before the beginning of the document title. Similarly for "footer", which is rendered after the end of the document. Details here: http://docutils.sf.net/docs/ref/rst/directives.html#document-header-footer Get it while it's hot, directly from the SVN repository or from a snapshot. Enjoy! -- David Goodger -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 253 bytes Desc: OpenPGP digital signature Url : http://mail.python.org/pipermail/doc-sig/attachments/20050407/a52a0224/signature.pgp From martin.blais at gmail.com Wed Apr 20 17:38:47 2005 From: martin.blais at gmail.com (Martin Blais) Date: Wed Apr 20 17:38:51 2005 Subject: [Doc-SIG] writing python-like documentation Message-ID: <8393fff05042008384efa9b8@mail.gmail.com> hi i recently converted some old documentation that i made for a client using docutils into the python's LaTeX documentation format (I wish i could stick with docutils and generate Python-looking docs, but it doesn't have all the specific markup for that yet (I think...), i wish!). anyway, i find it so pretty (well, it looks just like the python docs so that gives me a warm fuzzy feeling) that i am now contemplating writing documentation for my web application framework. independendly, i saw in the README or somewhere that the Python docs will be moved to an XML format and that the tools are "almost ready" for this (like the tools are already usable). where can i find out more about the new XML input format for python documentation and the tools that are used for it? I wouldn't mind busting through a few bugs if i'm using the next gen of python docs... also, is it usable yet? who's using it? is there example input? thanks for any pointers. cheers, From martin.blais at gmail.com Wed Apr 20 19:39:57 2005 From: martin.blais at gmail.com (Martin Blais) Date: Wed Apr 20 19:39:59 2005 Subject: [Doc-SIG] two subjects: docutils for python docs, and integrating documentation in source code Message-ID: <8393fff0504201039723adaf0@mail.gmail.com> 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-/Docs directory) From martin.blais at gmail.com Wed Apr 20 19:45:50 2005 From: martin.blais at gmail.com (Martin Blais) Date: Wed Apr 20 19:45:53 2005 Subject: [Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code In-Reply-To: <8393fff0504201039723adaf0@mail.gmail.com> References: <8393fff0504201039723adaf0@mail.gmail.com> Message-ID: <8393fff05042010456060af1e@mail.gmail.com> (sorry i sent this by mistake, d**n gmail doesn't have a confirm-before-send feature, completing below...) (2) > 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 problems with (a): - full reference to all the stuff in a module file is often inadequate, there is too much informatino, lots of irrelevant stuff - no space for examples and other kinds of explanations - ordering is source-code based, which is not the best for documentation > b. manual docs, which are written in LaTeX - they're great, but they live in a separate file! - some duplication of information that is available in docstrings i wrote a little prototype idea in 10 minutes to demonstrate what i mean, download the attached script and run it on the attached module. this is really just jotted down quickly, much work would have to be done on this for it to be usable, but it demonstrates the idea. basically, the idea would be to add a special string for each module, whose role would be to patch together the various docstirngs available in the module in a way that is readable and that exposes only what is needed. this way the Python modules documentation could probably be integrated in the source code... wouldn't that make sense? any thoughts appreciated. -------------- next part -------------- A non-text attachment was scrubbed... Name: pydocgen Type: application/octet-stream Size: 2519 bytes Desc: not available Url : http://mail.python.org/pipermail/doc-sig/attachments/20050420/af4c0a36/pydocgen.obj -------------- next part -------------- A non-text attachment was scrubbed... Name: gentest.py Type: application/octet-stream Size: 2615 bytes Desc: not available Url : http://mail.python.org/pipermail/doc-sig/attachments/20050420/af4c0a36/gentest.obj From mwh at python.net Wed Apr 20 19:59:16 2005 From: mwh at python.net (Michael Hudson) Date: Wed Apr 20 19:59:20 2005 Subject: [Doc-SIG] writing python-like documentation In-Reply-To: <8393fff05042008384efa9b8@mail.gmail.com> (Martin Blais's message of "Wed, 20 Apr 2005 11:38:47 -0400") References: <8393fff05042008384efa9b8@mail.gmail.com> Message-ID: <2macnt72iz.fsf@starship.python.net> Martin Blais writes: > independendly, i saw in the README or somewhere that the Python docs > will be moved to an XML format and that the tools are "almost ready" > for this (like the tools are already usable). This is a lie, I think, or at best wildly optimistic. I don't think there's been any work on this for well over a year. Cheers, mwh -- Gullible editorial staff continues to post links to any and all articles that vaguely criticize Linux in any way. -- Reason #4 for quitting slashdot today, from http://www.cs.washington.edu/homes/klee/misc/slashdot.html From mike at pcblokes.com Fri Apr 22 11:01:56 2005 From: mike at pcblokes.com (Michael Foord) Date: Fri Apr 22 11:02:26 2005 Subject: [Doc-SIG] two subjects: docutils for python docs, and integrating documentation in source code In-Reply-To: <8393fff0504201039723adaf0@mail.gmail.com> References: <8393fff0504201039723adaf0@mail.gmail.com> Message-ID: <4268BD84.9010601@pcblokes.com> Martin Blais wrote: >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... > > > [snip..] A brief but resounding +1 to the idea of standardising Python doc generation using docutils. The python documentation is very nicely presented and *ought* to be the standard style for people documenting third party modules. The toolset to produce the documentation currently seems a bit arcane. I may just be a luddite - but every time I've looked into it I've ended up with a headache (although I've not put any degree of real effort into it !). Being able to write docs in reST and use docutils to produce them sounds great. The *main* drawback will be that docutils doesn't yet support multipage documents. Best Regards, Fuzzyman http://www.voidspace.org.uk/python From mwh at python.net Fri Apr 22 11:26:18 2005 From: mwh at python.net (Michael Hudson) Date: Fri Apr 22 11:26:24 2005 Subject: [Doc-SIG] two subjects: docutils for python docs, and integrating documentation in source code In-Reply-To: <4268BD84.9010601@pcblokes.com> (Michael Foord's message of "Fri, 22 Apr 2005 10:01:56 +0100") References: <8393fff0504201039723adaf0@mail.gmail.com> <4268BD84.9010601@pcblokes.com> Message-ID: <2mwtqv40xx.fsf@starship.python.net> Michael Foord writes: > A brief but resounding +1 to the idea of standardising Python doc > generation using docutils. Are you talking about the existing Python documentation? Or just a way of making the "blue arrows" HTML from ReST? The issue with the existing documentation is that it exists, and in latex... > The python documentation is very nicely presented and *ought* to be > the standard style for people documenting third party modules. The > toolset to produce the documentation currently seems a bit arcane. I > may just be a luddite - but every time I've looked into it I've ended > up with a headache (although I've not put any degree of real effort > into it !). On Unix with a working Latex installation, it's really easy (these days, now Latex2HTML is less of a pig to install). > Being able to write docs in reST and use docutils to produce them > sounds great. The *main* drawback will be that docutils doesn't yet > support multipage documents. ISTR talk of a writer that wrote latex in the style of the existing Python documentation, which would get around that problem (but not the toolchain ones). Cheers, mwh -- "Fetch me my internet pants." -- from Twisted.Quotes From mike at pcblokes.com Fri Apr 22 11:47:40 2005 From: mike at pcblokes.com (Michael Foord) Date: Fri Apr 22 11:48:10 2005 Subject: [Doc-SIG] two subjects: docutils for python docs, and integrating documentation in source code In-Reply-To: <2mwtqv40xx.fsf@starship.python.net> References: <8393fff0504201039723adaf0@mail.gmail.com> <4268BD84.9010601@pcblokes.com> <2mwtqv40xx.fsf@starship.python.net> Message-ID: <4268C83C.1050301@pcblokes.com> Michael Hudson wrote: >Michael Foord writes: > > > >>A brief but resounding +1 to the idea of standardising Python doc >>generation using docutils. >> >> > >Are you talking about the existing Python documentation? Or just a >way of making the "blue arrows" HTML from ReST? > > > From my POV - just blue arrows HTML from reST would be hunky dory. I guess it might already be possible with judicious use of header, footer, and CSS. Perhaps I should investigate - more docutils directives to support documentation of python support would be a a definite plus as well though. >The issue with the existing documentation is that it exists, and in >latex... > > > Right - is Python documentation really written straight into LaTex markup ? >>The python documentation is very nicely presented and *ought* to be >>the standard style for people documenting third party modules. The >>toolset to produce the documentation currently seems a bit arcane. I >>may just be a luddite - but every time I've looked into it I've ended >>up with a headache (although I've not put any degree of real effort >>into it !). >> >> > >On Unix with a working Latex installation, it's really easy (these >days, now Latex2HTML is less of a pig to install). > > > >>Being able to write docs in reST and use docutils to produce them >>sounds great. The *main* drawback will be that docutils doesn't yet >>support multipage documents. >> >> > >ISTR talk of a writer that wrote latex in the style of the existing >Python documentation, which would get around that problem (but not the >toolchain ones). > > > Hmm.. I haven't heard any talk of such a latex writer on docutils-users... at least not in the last year. Best Regards, Fuzzy http://www.voidspace.org.uk/python >Cheers, >mwh > > > From mwh at python.net Fri Apr 22 12:02:05 2005 From: mwh at python.net (Michael Hudson) Date: Fri Apr 22 12:02:07 2005 Subject: [Doc-SIG] two subjects: docutils for python docs, and integrating documentation in source code In-Reply-To: <4268C83C.1050301@pcblokes.com> (Michael Foord's message of "Fri, 22 Apr 2005 10:47:40 +0100") References: <8393fff0504201039723adaf0@mail.gmail.com> <4268BD84.9010601@pcblokes.com> <2mwtqv40xx.fsf@starship.python.net> <4268C83C.1050301@pcblokes.com> Message-ID: <2msm1j3zaa.fsf@starship.python.net> Michael Foord writes: > From my POV - just blue arrows HTML from reST would be hunky dory. I > guess it might already be possible with judicious use of header, > footer, and CSS. Perhaps I should investigate - more docutils > directives to support documentation of python support would be a a > definite plus as well though. Well, I'm fairly sure I've seen this discussed somewhere, and don't think I've been making things up this time :) >>The issue with the existing documentation is that it exists, and in >>latex... >> >> > Right - is Python documentation really written straight into LaTex markup ? Yes. >>ISTR talk of a writer that wrote latex in the style of the existing >>Python documentation, which would get around that problem (but not the >>toolchain ones). >> >> > > Hmm.. I haven't heard any talk of such a latex writer on > docutils-users... at least not in the last year. Well, I think I saw it *somwhere*... no sure where, though. Cheers, mwh -- Never meddle in the affairs of NT. It is slow to boot and quick to crash. -- Stephen Harris -- http://home.xnet.com/~raven/Sysadmin/ASR.Quotes.html From Felix.Wiemann at gmx.net Fri Apr 22 14:23:37 2005 From: Felix.Wiemann at gmx.net (Felix Wiemann) Date: Fri Apr 22 14:25:27 2005 Subject: [Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code References: <8393fff0504201039723adaf0@mail.gmail.com> Message-ID: <874qdzngom.fsf@news2.ososo.de> Martin Blais wrote: > 1. writing python documentation using docutils, is it possible? Not currently. > here's a cool idea, i don't know if it's been discussed here before, Not that I know of. > 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. Looks nice. +1. > 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... That's a must-have, indeed, otherwise Docutils won't be able to generate genuine Python documentation. (Let's not talk about moving the whole Python documentation system to Docutils; that's too far in the future.) > 2. unifying source code and readable documentation I'm not sure if we want that because source documentation is for developers and external documentation is for users, but it's certainly worth thinking about. > [...] it seems to me that auto-generated documentation tools should > really be part of python. Docutils will be ready at the earliest in a few years. Dunno about Epydoc though. > 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) No, let's pick up the methods automatically. The methods *can* be reordered by just moving them around. > 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. :: .. role:: function :function:`foo` In the stylesheet for the new LaTeX writer which I'm currently developing:: \providecommand{\DCfunction}[2]{\function{#2}} I have a deadline next Wednesday, so I'll probably upload the new LaTeX writer then. -- For private mail please ensure that the header contains 'Felix Wiemann'. http://www.ososo.de/ From martin.blais at gmail.com Fri Apr 22 15:01:00 2005 From: martin.blais at gmail.com (Martin Blais) Date: Fri Apr 22 15:01:03 2005 Subject: [Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code In-Reply-To: <874qdzngom.fsf@news2.ososo.de> References: <8393fff0504201039723adaf0@mail.gmail.com> <874qdzngom.fsf@news2.ososo.de> Message-ID: <8393fff05042206014362b8fd@mail.gmail.com> On 4/22/05, Felix Wiemann wrote: > Martin Blais wrote: > > 2. unifying source code and readable documentation > > I'm not sure if we want that because source documentation is for > developers and external documentation is for users, but it's certainly > worth thinking about. oh, yes, but i was implying "for the library modules documentation". in other words, there will always be a need to write documentation outside of the code, but for the individual modules themselves, it would make sense to be able to put the docs in the code itself; advantages are: 1. one source, easier for developers to keep it up to date 2. distribution of docs is easier 3. reuse of docstrings within the same file we could conceptualize a template system like i mentioned before whose template can live either inside the file, or separately (but still able to fetch bits of docstrings). > > > [...] it seems to me that auto-generated documentation tools should > > really be part of python. > > Docutils will be ready at the earliest in a few years. Dunno about > Epydoc though. looks to me like docutils is very usable already... > > 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) > > No, let's pick up the methods automatically. The methods *can* be > reordered by just moving them around. i thought about this, and by fiddling around with pydoc with some of the stdlib module sources, came to a conclusion that this would not be enough. sometimes source code functions are grouped in a way that make sense in a structured programming approach, i.e. you can have a functoin foohelper() directly after foo(), but foohelper() really should not be in the documentation at all. or perhaps it should be in a special "Helper" section in the generated docs. however in the code, some of the data structures it uses were created in foo(), and as such it really makes sense to put its implementation next to foohelper() (note that in C++ since you have separate declaration and definition you don't have that problem and automated code generators use that, they can use on the ordering in the header files). also, and more obviously, many methods or functions simply don't need to appear in the documentation. try pydoc on some modules with classes, you'll see what i mean. you get some bits of content, and lots of noise. IMO this is very important if we're going to produce documentation that is readable, like the one that currently exists, we can't just pick up all the methods. perhaps we could provide an easy way to pick up all the methods if desired? e.g.:: ..classdescref:: modules.classname ..methods:: modules.classname > > 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. > > :: > > .. role:: function > > :function:`foo` > > In the stylesheet for the new LaTeX writer which I'm currently > developing:: > > \providecommand{\DCfunction}[2]{\function{#2}} > > I have a deadline next Wednesday, so I'll probably upload the new LaTeX > writer then. nice. but note that these generate index entries for code declarations (i.e. function, class, data). these are "easy" since they have their own syntactic units. what i meant is that it is not currently possible to generate generic index entries with docutils (not that i know of anyway), e.g. in a paragraph of normal text, how do i indicate that a word in the paragraph should appear in the index? at some point we're entreing the zone where the question becomes: can docutils be as complete a document preparation system as LaTeX? and the answer is obviously no and it never will be, but i suppose my question is, how close can we get? we don't need all the features that latex offers for the technical documentation. we should list all the essential ones (not compromising on any the existing ones), and see if they can all be implemented in docutils. we should also see what can be improved. in particular, the following things should be improved about the current documentatoin input: - the optional parameters markup should be grouped rather than nested with \optional. it makes more sense to declare them this way in Python because of the keywords syntax for function calls (e.g. foot(bli=4)); - there is no way to declare the base classes. The problem is that the syntax for the constructor (documentation) takes the space of inheritance (source code); - there needs to be a way to write a documentation paragraph for many methods/functions at the same time. i haven't found how to do this nicely yet, apart from breaking the declarations of functions outside of the classdesc; - there should be a formal syntax to describe the role of each of the arguments, as well as for the return value. Parsing the code for doc generation should validate that all the arguments are covered in the documentation string (this could be an option, and a condition for merging code). many people have suggested ways of doing this. any ideas appreciated. cheers, From Felix.Wiemann at gmx.net Fri Apr 22 15:57:19 2005 From: Felix.Wiemann at gmx.net (Felix Wiemann) Date: Fri Apr 22 16:01:34 2005 Subject: [Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code References: <8393fff0504201039723adaf0@mail.gmail.com> <4268BD84.9010601@pcblokes.com> <2mwtqv40xx.fsf@starship.python.net> Message-ID: <87zmvqnccg.fsf@news2.ososo.de> Michael Hudson wrote: > Michael Foord writes: > >> A brief but resounding +1 to the idea of standardising Python doc >> generation using docutils. > > Are you talking about the existing Python documentation? Or just a > way of making the "blue arrows" HTML from ReST? I think there's no need to make blue arrows from reST (yet). The first step to do would be to have a way to generate LaTeX code suitable for the current tool-chain. > The issue with the existing documentation is that it exists, and in > latex... Since the LaTeX code is quite well-structured, I suppose it's possible to convert it to reST. But that's at least one step too early now. First thing to do is implementing directive- and role-equivalents for all macros described at . And maybe we could use a standard way of passing multiple parameters to a role (see for examples of where that's needed). However, the (probably better) alternative to a unified way of passing multiple parameters is to have the role handler code do its own individual parsing, e.g. :versionchanged:`2.4: New flag XY.` for the two parameters ``2.4`` and ``New flag XY.`` (separated by ": "), and :manpage:`latex(1)` for ``latex`` and ``1``. Both roles take multiple parameters, but they have different ways of separating them. -- For private mail please ensure that the header contains 'Felix Wiemann'. http://www.ososo.de/ From goodger at python.org Sat Apr 23 06:56:00 2005 From: goodger at python.org (David Goodger) Date: Sat Apr 23 06:56:10 2005 Subject: [Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code In-Reply-To: <8393fff05042010456060af1e@mail.gmail.com> References: <8393fff0504201039723adaf0@mail.gmail.com> <8393fff05042010456060af1e@mail.gmail.com> Message-ID: <4269D560.50403@python.org> [Martin Blais] > 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, Yes, it's possible (or should/will be), and it has been discussed :-) Some work has already been done. I summarized it here: http://docutils.sf.net/sandbox/README.html#documenting-python > but do you think it would be possible to add docutils directives for > all the markup that the python documentation requires? Yes. > ( in particular, there could be directives to automatically extract > much of the information from the python declaratoins themselves, > using inspection ) That's a different issue: auto-documentation. Documented here: http://docutils.sf.net/docs/peps/pep-0258.html#python-source-reader http://docutils.sf.net/docs/dev/pysource.html http://docutils.sf.net/docs/dev/todo.html#python-source-reader The two issues should be dealt with separately. > 2. unifying source code and readable documentation This is a debate that's been going on for a long time. I'm not going to get into it again :-) > 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. You're talking about "literate programming": http://www.literateprogramming.com/ > also, one thing that i can't see is how to generate index entries > from docutils. Hasn't been implemented yet, but there are ideas: http://docutils.sf.net/docs/dev/rst/alternatives.html#index-entries-indexes > also, for typed references e.g. \function{foo}, i don't > know how you would do that in docutils. :function:`foo` > 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... Um, yeah ;-) But there's a lot of work to be done, decisions to be made, issues to be thought out. -- David Goodger -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 253 bytes Desc: OpenPGP digital signature Url : http://mail.python.org/pipermail/doc-sig/attachments/20050423/0436145a/signature.pgp From martin.blais at gmail.com Sat Apr 23 16:11:20 2005 From: martin.blais at gmail.com (Martin Blais) Date: Sat Apr 23 16:11:26 2005 Subject: [Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code In-Reply-To: <4269D560.50403@python.org> References: <8393fff0504201039723adaf0@mail.gmail.com> <8393fff05042010456060af1e@mail.gmail.com> <4269D560.50403@python.org> Message-ID: <8393fff05042307114da3643c@mail.gmail.com> On 4/23/05, David Goodger wrote: > [Martin Blais] > > 2. unifying source code and readable documentation > > This is a debate that's been going on for a long time. I'm not going > to get into it again :-) well, i didn't mean necessarily that we should convert fred's docs back into the source code, but that there should be a way for people to be able to do that in their own libraries. but certainly we should make something that is good enough to be able to do that with the python sources themselves... > > > 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. > > You're talking about "literate programming": > http://www.literateprogramming.com/ yes and no. there exists some codes should not appear in the documentation (answer: pull model with templating system). there exists some documentations that should not appear in the code, more generic manuals (answer: separate file, pull model for selected code bits). i'm trying to find a middle ground. cheerrs, thx for the links, From Felix.Wiemann at gmx.net Sat Apr 30 19:21:23 2005 From: Felix.Wiemann at gmx.net (Felix Wiemann) Date: Sat Apr 30 19:21:42 2005 Subject: [Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code References: <8393fff0504201039723adaf0@mail.gmail.com> <874qdzngom.fsf@news2.ososo.de> <8393fff05042206014362b8fd@mail.gmail.com> Message-ID: <87d5scyycs.fsf@news2.ososo.de> Martin Blais wrote: > Felix Wiemann wrote: > >>> [...] it seems to me that auto-generated documentation tools should >>> really be part of python. >> >> Docutils will be ready at the earliest in a few years. Dunno about >> Epydoc though. > > looks to me like docutils is very usable already... Oh, yes, no doubt about that. :-) >> No, let's pick up the methods automatically. The methods *can* be >> reordered by just moving them around. > > [Bad idea, because:] sometimes source code functions are grouped in a > way that make sense in a structured programming approach [...] That's true. > [...] many methods or functions simply don't need to appear in the > documentation Maybe add a special token to the docstring that the method shouldn't appear in auto-documentation? > perhaps we could provide an easy way to pick up all the methods if > desired? e.g.:: > > ..classdescref:: modules.classname > ..methods:: modules.classname Looks good, IMO. >> :function:`foo` >> >> In the stylesheet for the new LaTeX writer which I'm currently >> developing:: >> >> \providecommand{\DCfunction}[2]{\function{#2}} > > [...] but note that these generate index entries for code declarations > (i.e. function, class, data). these are "easy" since they have their > own syntactic units. what i meant is that it is not currently > possible to generate generic index entries with docutils, e.g. in a > paragraph of normal text, how do i indicate that a word in the > paragraph should appear in the index? * Write index support for Docutils and use a special role. Or: * If you only need index support for the LaTeX output, do :: .. role:: index A paragraph with a `word`:index: which appears in the index. and implement it in LaTeX like for the :function: role above, except that you use a macro (let's call it ``\addtoindex``) of some (existing) indexing system, so that you have e.g. :: \providecommand{\DCindex}[2]{\addtoindex{#2}#2} > at some point we're entreing the zone where the question becomes: can > docutils be as complete a document preparation system as LaTeX? LaTeX is certainly more powerful as long as Docutils doesn't have plugin support, but for most practical purposes, Docutils can serve as document preparation system quite well. David Abrahams even wrote a book with reStructuredText, and that was quite some time ago, when Docutils was less powerful than now. You can't do sophisticated typesetting with Docutils, though. > and the answer is obviously no and it never will be, Add extension support and Docutils is as "complete" as LaTeX. And much more usable in practice. > in particular, the following things should be improved about the > current documentatoin input: > > - the optional parameters markup should be grouped rather than nested with > \optional. it makes more sense to declare them this way in Python because > of the keywords syntax for function calls (e.g. foot(bli=4)); (That transformation can be done automatically if we generate documentation using Docutils.) > - there is no way to declare the base classes. The problem is that the syntax > for the constructor (documentation) takes the space of inheritance (source > code); I don't understand. Could you elaborate (maybe with an example), please? > - there needs to be a way to write a documentation paragraph for many > methods/functions at the same time. i haven't found how to do this > nicely yet, apart from breaking the declarations of functions > outside of the classdesc; > > - there should be a formal syntax to describe the role of each of the > arguments, as well as for the return value. Parsing the code for doc > generation should validate that all the arguments are covered in the > documentation string (this could be an option, and a condition for > merging code). many people have suggested ways of doing this. I can't comment on these points (maybe Fred can). -- For private mail please ensure that the header contains 'Felix Wiemann'. http://www.ososo.de/ From martin.blais at gmail.com Sat Apr 30 22:00:15 2005 From: martin.blais at gmail.com (Martin Blais) Date: Sat Apr 30 22:00:18 2005 Subject: [Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code In-Reply-To: <87d5scyycs.fsf@news2.ososo.de> References: <8393fff0504201039723adaf0@mail.gmail.com> <874qdzngom.fsf@news2.ososo.de> <8393fff05042206014362b8fd@mail.gmail.com> <87d5scyycs.fsf@news2.ososo.de> Message-ID: <8393fff05043013004e5589c5@mail.gmail.com> On 4/30/05, Felix Wiemann wrote: > Martin Blais wrote: > > - there is no way to declare the base classes. The problem is that the syntax > > for the constructor (documentation) takes the space of inheritance (source > > code); > > I don't understand. Could you elaborate (maybe with an example), > please? look at, for example, class Decimal in the docs: http://docs.python.org/lib/node177.html class Decimal( [value [, context]]) Constructs a new Decimal object based from value. in the source code, the declaration: class ClassName(...): has ... replaced by the base class. in the docs, it's used for the constructor. this is only slightly confusing. so then, where do you declare a base class? cheers,