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

[Michael Hrivnak]

I see that the task has not had any activity for a while. It would be good
to nail this down. I asked a question on the task about how we plan to do
the conversion, and I think it's important to answer that before we commit
to the change.

https://pulp.plan.io/issues/2347#note-12

It appears that in a couple of places, the Google style has already been
employed. To my knowledge, no decision has been made yet, nor do I think we
should make a change like this until we have a plan in place and all
questions answered. I don't see any reason why we can't make a plan and
move forward, but let's please proceed with an orderly transition.

Perhaps one or more people who are particularly interested in this change
would be willing to take the reigns and try to get this task groomed and
accepted onto the next sprint. Any volunteers?

Thanks,
Michael

On Thu, Oct 27, 2016 at 12:53 PM, Brian Bouterse <bbouters at redhat.com>
wrote:

> Also +1. Is this story ready to be groomed and marked as a sprint
> candidate=yes?
>
> https://pulp.plan.io/issues/2347
>
>
> On Wed, Oct 26, 2016 at 5:07 PM, Jeff Ortel <jortel at redhat.com> wrote:
>
>> +1 switching to Napoleon.
>>
>> On 10/17/2016 10:14 AM, 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 think Napoleon's page in the sphinx docs explain this pretty well:
>> > http://www.sphinx-doc.org/en/stable/ext/napoleon.html
>> >
>> > I've got like three more RFCs queued up; I'm trying to be nice and not
>> overload
>> > pulp-dev with all my crazy ideas simultaneously. :)
>> >
>> >
>> >
>> > _______________________________________________
>> > Pulp-dev mailing list
>> > Pulp-dev at redhat.com
>> > https://www.redhat.com/mailman/listinfo/pulp-dev
>> >
>>
>>
>> _______________________________________________
>> Pulp-dev mailing list
>> Pulp-dev at redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
>>
>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20161128/d4f32e86/attachment.htm>