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

[Patrick Creech]

On Mon, 2016-10-17 at 11:14 -0400, Sean Myers wrote:
> I'd love it if we could stop writing docs in the ":param foo:" style. Instead,
> I think that we should use the sphinx extension "napoleon" to write docstrings
> that are *way* more human-readable (in my opinion, at least) while still
> generating good sphinx docs.

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.  Assuming
separation between the params for clarity, you can easily take up 3 lines of information for a
single piece of data.

> I think Napoleon's page in the sphinx docs explain this pretty well:
> http://www.sphinx-doc.org/en/stable/ext/napoleon.html

I really like this format, surprisingly.  You go to the args section, find your variable, then have
the information you need.  I really like how compact and succint it is, and it doesn't require me to
go to a new line to get all the info I need for a variable.  Also, the variable name is the first
item on the line, making it easier to identify from a scanning perspective


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20161017/54501e6d/attachment.sig>