[Doc-SIG] Re: two subjects: docutils for python docs, and integrating documentation in source code

[Felix Wiemann]

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/