[Pulp-dev] RFC: Use Napoleon when Writing Docs
Austin Macdonald
amacdona at redhat.com
Tue Oct 18 12:31:31 UTC 2016
Speaking of visual assaulting format.... rewritten as a Task
I hope I am not stepping on toes here, but if I was going to take the
time to get format this in a way that makes my point, I figured I might
as well go ahead and do it on an issue.
https://pulp.plan.io/issues/2347
On 10/18/2016 08:15 AM, Austin Macdonald wrote:
> 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
>
> """
-------------- 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/119e8741/attachment.sig>
More information about the Pulp-dev
mailing list