[Python-Dev] Questions/comments on documentation formatting (original) (raw)

Benjamin Peterson benjamin at python.org
Tue Jan 20 04:01:08 CET 2009

On Mon, Jan 19, 2009 at 8:24 PM, Brett Cannon <brett at python.org> wrote:

I have been writing up the initial docs for importlib and four things struck me:

1. Why is three space indents the preferred indentation level?

Because it matches nicely up with the length of directives:

.. somedirective:: blah ^^^

2. Should we start using function annotations?

No, I think that information is better stored in the function description.

3. Are brackets for optional arguments (e.g. ``def fxn(a [, b=None [, c=None]])``) really necessary when default argument values are present? And do we really need to nest the brackets when it is obvious that having on optional argument means the rest are optional as well?

Actually, the defaults are usually documented in the description not the signature.

4. The var directive is not working even though the docs list it as a valid directive; so is it still valid and something is broken, or the docs need to be updated?

The docs should be updated. "data" is the one to use now.

-- Regards, Benjamin

More information about the Python-Dev mailing list