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

[Fred L. Drake, Jr.]

On Friday 22 April 2005 09:01, Martin Blais wrote:
 > 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?

We actually don't have a construct for that in the LaTeX, either.  Index 
entries are made in addition to the actual text.  It would be easy to add 
something like that, though, but I don't know that it would be used often.

We have a lot of specialized LaTeX macros for index entries now, to support 
various combinations of nouns and adjectives with up to four words being 
combined in near-combinatorial patterns.  We probably don't need that many; 
most are not used extensively, and rarely in newer documentation.  (Newer 
documentation is more likely to contain multiple index entries with just some 
of the combinations, which seems more sane to me.)

 > 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));

The \optional stuff has become very painful; I'm interested in suggestions on 
how it should be structured.

The existing markup is based very heavily in what was in Python from 
1995-1998; things have changed a good bit since then.  Some issues that have 
to be considered:

- For some functions (especially common with those implemented in C), nesting
  things using \optional{arg\optional{, arg}} actually reflects the call
  signature.  We have to be able to do this.

- Some functions accept keyword-only arguments that can't be provided using
  positional arguments at all (using **keywords).  We don't have a good way of
  dealing with this now.

- Some functions have signatures that are best described using multiple
  signatures.  (Consider type() as an example.)  For these, some benefit from
  separate descriptions for each signature, and others can reasonably share
  descriptions among signatures.

 > - 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 agree that this is a problem.  We also don't have good ways to indicate 
class methods and static methods.  The need to describe things provided by 
specialized descriptors will only become more complicated as @decorators gain 
more traction.

 > - 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,

We need a better way to display these groupings as well; they aren't terribly 
obvious in the existing LaTeX documentation where they exist.  I suspect the 
right presentation will be very different in the HTML and typeset versions.

 >   apart from breaking the declarations of functions outside of the
 > classdesc;

I don't know what you mean by this.  Are you actually describing methods 
inside the {classdesc} environment using nested {methoddesc}s and 
{memberdesc}s?

 > - 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.

Verification can certainly be optional.  It would also need have a way to say 
"skip it for this function" in cases where magical games are being played 
with *args and **kw.  And it would need to undestand that documenting an 
argument in a base class may be sufficient (that's a policy decision).


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>