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

[Michael Hrivnak]

It's hard to say "yes" with a variable-width font, but here's an example of
what I find very readable:

https://github.com/pulp/crane/blob/2.0.0/crane/views/v1.py#L173-L179

I like information in tables and have spent too much of my life in
spreadsheets, so that could be causing an aesthetic bias. :)

Michael

On Mon, Oct 17, 2016 at 2:43 PM, Sean Myers <sean.myers at redhat.com> wrote:

> On 10/17/2016 02:32 PM, Michael Hrivnak wrote:
> > I personally find their RST example to be a "jumble" only because the
> > second column isn't aligned. I find the RST style to be easier to read
> than
> > Napoleon when it's correctly aligned, although admittedly it does take a
> > small amount of effort to keep it aligned. Both are fine options, and I'd
> > be quite happy either way.
>
> To be clear, you're saying that this...
>
>     """
>     Fields:
>
>     :cvar url: The URL used to download the related artifact.
>     :type url: django.db.models.TextField
>
>     Relations:
>
>     :cvar artifact: The artifact that is expected to be present at ``url``.
>     :type artifact: pulp.app.models.Artifact
>     :cvar importer: The importer that contains the configuration necessary
>                     to access ``url``.
>     :type importer: pulp.app.models.Importer
>
>     """
>
> ...is easier to read than this?
>
>     """
>     Fields:
>
>         url (models.TextField): The URL used to download the related
> artifact.
>
>     Relations:
>
>         artifact (Artifact): The artifact that is expected to be present
> at ``url``.
>         importer (Importer): The importer that contains the
>             configuration necessary to access ``url``.
>
>     """"
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20161017/f4bb1ed1/attachment.htm>