[Doc-SIG] two simple, but important questions

[Edward D. Loper]

I don't have strong opinions on Travis's questions, and I think that
they do not necessarily have to be addressed in the PEP..  But I'll
give my thoughts on them anyway..

Travis Rudd said:
>> Should the API documentation be written solely in docstrings that are  
>> accessible at runtime through __doc__?  (option a)
>> 
>> 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)

Given the option of producing .pyo files, I would lean towards option
(a).  The problem with your solution here (using a tool to read the
.py file) is that it requires that everyone have the .py files for all
the modules they're using.  But sometimes it's useful to distribute
just the .pyc file..

The main advantage I see of putting formatted docs anywhere other than
the docstring is that some existing programs (Zope?) already use
the docstrings for specific purposes, that are incompatible with
what we would propose...

>> 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)?  

In general, if you want the docs on a module, then you should trust it
enough to import it anyway.  Presumably if you're trying to get its
docs, it's because you want to *use* it...

That said, there are some definite advantages of processing the source
code..  e.g., you can list default args as what they really are, instead
of something like <function <lambda> at 0xabcdef>.  and you can tell
what's imported and what's not.  

But I would say that both options should be available to tools.  It
may turn out that tools that implement one option will be more 
successful, and so will become widely accepted and everyone will
forget about the other option.  Or it might be that the best approach
is to use both, when possible..

---

As a final note, I think that if this PEP is going to have any chance
of succeeding, it needs to have a relatively small and well-defined
scope.  So maybe we can divide it in two:
  PEP A: a standard markup/string format for "formatted documentation 
         strings"
  PEP B: a proposal on how "formatted documentation strings" should
         be accessed, where they should be stored, etc.

-Edward