[Python-Dev] Questions/comments on documentation formatting

[Brett Cannon]

On Mon, Jan 19, 2009 at 19:01, Benjamin Peterson <benjamin at python.org> wrote:
> 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.
>

Why? Putting it in the signature makes it very succinct and a simple
glance at the doc to see what type/ABC is expected.

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

OK, but that doesn't make it optimal. And that still doesn't answer my
question of whether all of those nested brackets are truly necessary.

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

So the 'data' directive turns into any variable, not just a module variables?

-Brett