[Doc-SIG] two simple, but important questions

[Tavis Rudd]

I'm new to this SIG. After reading the archives I can't find any consensus 
about two critical issues that I feel should be at the forefront of any 
documentation PEP: issues that need to be addressed before the syntax of the 
markup language.  It seems like excellent progress is being made on the 
Structured Text and tools fronts, but what do  members of  
Doc-SIG feel about these issues? 

ONE:
-----
Should the API documentation be written solely in docstrings that are  
accessible at runtime through __doc__?  (option a)

Note to Edward: by API documentation I mean exactly what you said.

Or should more detailed documentation (i.e. the stuff in structured text) be 
written in a form that is not compiled into the byte-code, thus sparing the 
memory and processing overhead and keeping the namespace clean? (option b)
One way of doing this is to place as second """string literal""" after the 
__doc__ docstring.

Or, should it be kept separate from the __doc__ docstring 
but still be imported into the runtime environment (under a name like 
__fdoc__), at the cost of having to change the way python works internally? 
(option c)

TWO:
----
Should the documentation tools (a) import and run module code in order to 
produce the documentation or (b) should they follow the safer route of 
parsing the documentation out of the raw source code (.py)?  

I suppose if your perspective on issue one is to go for option b, then you'd 
have to get the extended docs from the raw source code.


MY PERSPECTIVE:
--------------
ONE:
I'd argue for option b, because:

- it requires absolutely no changes to python's internals and is backwards 
compatible --->> therefore it can be implemented today not when python 2.? is 
released as in option c.

- it keeps the namespace clean

- it maintains all the advantages of having a short synopsis of a function, 
class or object available through __doc__ at runtime, but also allows for 
more extensive documentation to be provided, and marked up with Structured 
Text

- *** all of the documentation can still be accessed at the interactive 
prompt (all you need is a help function as a wrapper for the doctool, and 
maybe a pager like in pydoc)

- it keeps module loading time minimal, once the .pyc file has been generated 
initially and it keeps memory use low

TWO:
For security and performance issues alone I argue for option b.  

Inheritance, etc. can be figured out parse-the-source-code doctools just as 
easily as with import-the-module doctools. Edward, I don't see how 
import-the-module doctools would have any advantage for documenting 
extensions to python in other languages.  The standard __doc__ strings would 
still be available, and parse-the-source-code doctools would be able to 
handle c, c++, java source without too much effort, plus numerous excellent 
tools already exist for this..

Cheers,
Tavis