[Python-Dev] Questions/comments on documentation formatting

[Brett Cannon]

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?

2. Should we start using function annotations?

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?

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?

-Brett