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

[Sean Myers]

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 --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20161017/1da9237b/attachment.sig>