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

[Brian Bouterse]

As Jeremy points out, it's a question of style choice. I am in favor of adopting the Google docstring style. It's grouping style is clear and the sections [0] look good too. I prefer that more than the one-line RST syntax that Jeremy gave an example of which would also be an improvement over what we do today.

Also if we enable Napoleon on the doc builders, it should support both Google docstring and the original RST style, so I don't think anything will break. This will let us migrate over time. I commented some on the ticket.

[0]: http://www.sphinx-doc.org/en/stable/ext/napoleon.html#sections
[1]: https://pulp.plan.io/issues/2347

-Brian

----- Original Message -----
> From: "Jeremy Audet" <jaudet at redhat.com>
> To: "Austin Macdonald" <amacdona at redhat.com>
> Cc: pulp-dev at redhat.com
> Sent: Thursday, October 20, 2016 8:58:27 AM
> Subject: Re: [Pulp-dev] RFC: Use Napoleon when Writing Docs
> 
> I've really got to butt in here and say that y'all may have a
> mis-understanding of what Sphinx lets you do. I'm seeing code examples like
> this:
> 
> :param repo_name: The name of the repo
> :type repo_name: basestring
> 
> And criticisms like this:
> 
> > 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.
> 
> But Sphinx also lets you document parameters like this:
> 
> :param basestring repo_name: The name of the repo
> 
> So - definitely consider switching to Napoleon or whatever you like. That's
> cool. But please, fully understand what Sphinx offers.
> 
> -Jeremy
> 
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>