[SciPy-dev] restructuredtext en docformat

[Alan G Isaac]

On Mon, 09 Jul 2007, dmitrey apparently wrote: 
> http://twistedmatrix.com/pipermail/twisted-bugs/2006-October/001609.html
>     epydoc has a epytext variant that's valid restructured 
>     text.  You can either set `__docformat__ 
>     = "restructuredtext en"` in your module, or pass 
>     `--docformat restructuredtext` to `epydoc` to use it. 


In my opinion, including the docformat declaration in each 
module is important.

- It is the friendly thing to do.  (I.e., it provides useful 
  information that is otherwise missing.)
- If doc standards change, not all modules will be changed 
  at once, so it will be crucial for modules to have this 
  inforamtion
- the docformat declaration can be used by other processors 
  (not just epydoc)
- epydoc users can always override the module level 
  docformat declaration at the command line, if desired

All that said, it does seem like it would be appropriate to 
be able to declare a docformat for an entire package in its 
__init__.py file.  I do not think this is currently 
possible.

Cheers,
Alan Isaac