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
signature.asc
Description: This is a digitally signed message part
_______________________________________________ Pulp-dev mailing list [email protected] https://www.redhat.com/mailman/listinfo/pulp-dev
