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


Attachment: signature.asc
Description: This is a digitally signed message part

_______________________________________________
Pulp-dev mailing list
Pulp-dev@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev

Reply via email to