[Pulp-dev] RFC: Use Napoleon when Writing Docs

[Jeremy Audet]

I've really got to butt in here and say that y'all may have a
mis-understanding of what Sphinx lets you do. I'm seeing code examples like
this:

    :param repo_name: The name of the repo
    :type  repo_name: basestring

And criticisms like this:

> I, personally, am not a big fan of the ":param foo:" syntax.  To me, it
puts way to much information
> spread across multiple lines, increasing the length/scrolling/brainpower
needed to parse such an
> item.  I have to read multiple lines just to figure out what type  a
variable has.

But Sphinx also lets you document parameters like this:

    :param basestring repo_name: The name of the repo

So - definitely consider switching to Napoleon or whatever you like. That's
cool. But please, fully understand what Sphinx offers.

-Jeremy
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20161020/12c71abf/attachment.htm>