[Doc-SIG] two simple, but important questions
Mon, 12 Mar 2001 21:14:17 -0800
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?
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
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?
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.
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
- *** 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
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..