[Python-Dev] Questions/comments on documentation formatting

[Brett Cannon]

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