[Doc-SIG] Python docs in reST

[Michael Foord]

Martin Blais wrote:

>>>>If I am writing a small (ish) module I can fulfill 1 and 2 with a decent
>>>>module docstring and proper docstrings for functions and classes etc. In
>>>>which case I *need* to be able to auto extract the docs and create a
>>>>reference doc from them.
>>>>
>>>>I *do not* want private methods visible in this documentation - and I do
>>>>want a way of specifying that a function/method should not be included.
>>>>
>>>>If the 'user' is a programmer, I don't think there is necessarily a
>>>>clear distinction between 1 and 2.
>>>>
>>>>
>>>>        
>>>>
>>>well, i would argue that what you want to do is (1),
>>>
>>>      
>>>
>>Yes :-)
>>
>>    
>>
>>>but you want it
>>>in the source file.
>>>
>>>
>>>      
>>>
>>Yes, and be able to generate an API doc from it.
>>
>>    
>>
>>>i was suggesting earlier that this could be implemented by adding a
>>>special docstring of your choice (e.g. __manual__) to your source
>>>code, it could even be at the end if you want it to.  whatever tool
>>>you use to generate documentation would first extract that flie before
>>>processing.
>>>
>>>
>>>
>>>
>>>      
>>>
>>Why not just use the module docstring ?
>>    
>>
>
>can you imagine scrolling past an entire manual everytime you open a new file?
>(i'm assuming we're writing real user documentation in that docstring,
>not just an overview)
>
>
>
>  
>
Ha :-)

OTOH can you imagine scrolling past an entire module just to get to the 
docs ;-)
If I'm writing something that requires a full doc then I wouldn't put it 
in a docstring - but for some *modules* [#]_ it is appropriate to 
include brief documentation in the source code.

I think you're right - there are two related but separate use cases.

1) Autogenerating API docs from source code.

2) Writing proper documentation - and included details from the source code.

The reasons **I** am unhappy with the existing tools [#]_ (i.e. epydoc) 
is that they don't allow me to mark constants/functions/classes/methods 
as private, and they don't allow me to document constants.

You could overcome these problems by parsing source code rather than 
importing and examining objects. You would obviously need to develop 
appropriate conventions.

I don't object to using a magic variable like '__manual__' - but I would 
want to obtain it by parsing rather than introspection. (In which case 
you could equally use a docstring at the end of a document).

In either case it would need work recommencing on the Pysource reader. 
I'm working on rest2web at the moment - but will have some time in the 
future to look at this - I do want to get further into the docutils 
source code.

Best Regards,

Fuzzy
http://www.voidspace.org.uk/python

.. [#] as opposed to a framework or application that will require more 
than just a description of functions/classes/methods
.. [#] For achieving number 1