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

Brett Cannon brett at python.org
Thu Jan 22 00:56:19 CET 2009

On Wed, Jan 21, 2009 at 13:53, Georg Brandl <g.brandl at gmx.net> wrote:

Brett Cannon schrieb:

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? As said, it matches directive content with directive headers nicely. Ben's solution is nice as well, but now that we have 3-space I'd rather we stick with 3-space (however, if you don't care, I'll not reformat 4-space indents :)

=) OK.

Code in code blocks should use 4-space as usual.

2. Should we start using function annotations? It's not really supported yet by Sphinx. Also, I don't know if it makes too much sense, given that it will reinforce the thinking of annotations as type declarations.

Fine by me.

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? We've discussed that once on the doc-SIG, and I agreed that the bracketing is not really pretty, especially if it's heavily nested. Python functions where it makes sense should use the default-value syntax, while C functions without kwargs support need to keep the brackets.

That was my thinking.

Making this consistent throughout the docs is no small task, of course.

Nope, but perhaps all new docs should stop their use.

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? (First, you're confusing "directive" and "role" which led to some confusion on Benjamin's part.) Where is a "var" role documented? If it is, it is a bug.

http://docs.python.org/dev/3.0/documenting/markup.html#inline-markup.

-Brett

More information about the Python-Dev mailing list