[Python-Dev] Questions/comments on documentation formatting

[Georg Brandl]

Brett Cannon schrieb:

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

OK. Perhaps we can sprint a bit on automatic replacement at PyCon.

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

I assume you're referring to "Variable names are an exception, they should
be marked simply with *var*."?  Do you have suggestions how to improve
clarity?

Georg