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

[David Goodger]

> Martin Blais wrote:
>> [...] many methods or functions simply don't need to appear in the
>> documentation

[Felix Wiemann]
> Maybe add a special token to the docstring that the method shouldn't
> appear in auto-documentation?

A special comment perhaps?  Or a function attribute?  I don't think
such metadata should be put in the docstring; that's for
documentation.

OTOH, the common convention for "weakly private" or "internal" can be
used: a single underscore prefix.  E.g.:

    def _internal(...):

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

Some ideas have been documented; see
http://docutils.sf.net/docs/dev/rst/alternatives.html#index-entries-indexes

--
David Goodger <http://python.net/~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/20050502/72a12d3a/signature.pgp