[Python-Dev] Questions/comments on documentation formatting
Georg Brandl
g.brandl at gmx.net
Wed Jan 21 22:53:42 CET 2009
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 :)
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.
> 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.
Making this consistent throughout the docs is no small task, of course.
> 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.
Georg
More information about the Python-Dev
mailing list