[Python-ideas] Conventions for Python code documentation
Guido van Rossum
guido at python.org
Tue Jan 20 19:43:37 CET 2015
IIUC there is no rst support in the stdlib, and including docutils sounds
like a bad idea (it's a huge unmaintained codebase).
On Tue, Jan 20, 2015 at 10:38 AM, Todd <toddrjen at gmail.com> wrote:
> On Jan 20, 2015 5:32 PM, "Guido van Rossum" <guido at python.org> wrote:
> > On Mon, Jan 19, 2015 at 10:39 PM, Terry Reedy <tjreedy at udel.edu> wrote:
> >> On 1/19/2015 2:54 PM, Guido van Rossum wrote:
> >>> Unfortunately PEP 257 falls short on specifying how to describe
> >>> arguments -- it has only one example, it's not normative, and there's
> >>> not much code that follows the example. The reST conventions are more
> >>> common, but the stdlib itself rarely uses them.
> >> Because I have not seen such used, except maybe once, I have been
> meaning to ask if I am allowed to use rst markup in stdlib docstrings?
> > I prefer you don't use them. We don't generate docs from the stdlib
> sources, and if someone generated them locally they would probably be doing
> themselves a disservice -- the docstrings exist for the benefit of the
> help() builtin, which AFAIK doesn't understand rst markup.
> Might the lack of rst support in help() be something to address either as
> part of this effort or in parallel with it?
> Python-ideas mailing list
> Python-ideas at python.org
> Code of Conduct: http://python.org/psf/codeofconduct/
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Python-ideas