[Doc-SIG] two simple, but important questions

[Tony J Ibbs (Tibs)]

Tavis Rudd wrote:
> I'm new to this SIG.

'Sok - more people means more brains to think useful thoughts.

> After reading the archives

and you're already coming across well!

> I can't find any consensus
> about two critical issues that I feel should be at the
> forefront of any  documentation PEP:

There's probably a good reason for that..

> issues that need to be addressed before
> the syntax of the markup language.

the most obvious of which *might* be a disagreement with that statement,
of course...

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

Well, this one is definitely one to leave for later arguments (see, I
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)

I think this has been answered elsewhere.

> One way of doing this is to place as second """string
> literal""" after the
> __doc__ docstring.

An idea I revile (sorry, I'm in a hurry)

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

Heck, I hate that too.

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

That's easy, the answer is yes.

More precisely, it depends on what you want to do.

pydoc, to meet its mandate, has to do one.

HappyDoc (and tools like it) have to do the other.

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

My arguments are elsewhere, but in summary:

docstrings are good - put documenation in them - whatever you *want* to
put in them (heh, getting *any* documentation is a win)

documentation is good - if you have more than will fit in a docstring,
put it in a text file.

See, I think I'm a traditionalist.

Of course, I won't moan if you want to do literate programming instead,
but that's a different kettle of fish.

> - 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.

Heh - all the software we've been writing works in 1.5.2...

> - it keeps the namespace clean

us too

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

Unfortunately (well, not really), you've already got both options, and
option (a) is BDLF approved.

Tibs


--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)