[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
> https://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/
>



-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150120/a7f402fd/attachment-0001.html>


More information about the Python-ideas mailing list