tldr; I'm strongly in favor of switching to Napoleon. I was not
previously opinionated on the matter, but after trying it out I see a
lot of benefits.
Reasoning: *We drown ourselves with useless information.*
:param repo_name: The name of the repo
:type repo_name: basestring
This obviously has a very low information density.
In Napoleon this would be:
Params:
repo (basestring): Name of a repository
Format can't fix awkward, and this is still not a super helpful comment,
but at least it takes up less space but contains the same information.
The lists will be shorter and less visually assaulting. On the topic of
visual assualt, `:param:` is the first part of the line, which is where
I would rather be scanning for variable names. **Napoleon presents
information in the order I look for it.**
Take a look at a comparison of larger docstrings from the wild:
_
__Current_
def _process_repos(repo_objs, details, importers,
distributors):
"""
Serialize repository objects and add related importers and
distributors if
requested.
Apply standard processing to a collection of repositories being
returned to a client.
Adds
the object link and optionally adds related importers and
distributors.
:param repo_objs: collection of repository
objects
:type repo_objs: list or tuple of pulp.server.db.model.Repository
objects
:param details: if True, include importers and distributors,
overrides other
values
:type details:
bool
:param importers: if True, adds related importers under the
attribute
"importers".
:type importers:
bool
:param distributors: if True, adds related distributors under the
attribute
"distributors"
:type distributors:
bool
:return: a list of serialized repositories with importer and
distributor data optionally
added
:rtype: list of
dicts
"""
_Napoleon
_ def _process_repos(repo_objs, details, importers,
distributors):
"""
Serialize repository objects and add related importers and
distributors if
requested.
Apply standard processing to a collection of repositories being
returned to a client.
Adds
the object link and optionally adds related importers and
distributors.
Args:
repo_objs (list or tuple of Repository): collection of
repository
objects
details (bool): if True, include importers and distributors,
overrides other
values
importers (bool): if True, adds related importers under the
attribute
"importers".
distributors (bool) if True, adds related distributors under
the attribute
"distributors"
Returns:
A list of serialized repositories with importer and distributor
data optionally
added
"""
On 10/17/2016 03:41 PM, Patrick Creech wrote:
> 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
>
>
>
>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 847 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20161018/4f8581f6/attachment.sig>