Pulp

mhrivnak was expressing an aesthetic preference for more tabular layouts. That's still possible with napoleon, so I thought I'd present it as another potential option:

    """ 
    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): 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:
          list: serialized repositories with importer and distributor data optionally added
    """    

I took some liberties with "repo_objs", because it ruins everything in both :sphinx: syntax and napoleon (sphinx doesn't really understand compound types like Repository[], the type of that arg should be list, or "Iterable" [0] )

I'm not a fan of this "tabular" style, but others might be. Thoughts?

[0]: https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable

+1 to this story. I want to edit it to replace s/Napolean/Google style docstrings/ to distinguish the style change versus the Sphinx plugin which will parse Google style docstrings. Am I OK to edit this some?

bmbouter wrote:

+1 to this story. I want to edit it to replace s/Napolean/Google style docstrings/ to distinguish the style change versus the Sphinx plugin which will parse Google style docstrings. Am I OK to edit this some?

Yeah, I think that's a great idea.

+1 to the story. I'm also not a fan of the tabular style.

I'm happy accepting this as groomed once we answer just one more question: what will the transition be like?

Options:

• Use the new style when writing new doc blocks, and optionally when updating old ones. Otherwise leave old ones as-is.
• Spend (a lot of) time converting all doc blocks to the new style.
• Find or make a tool to automatically do much of the conversion.

Preferences? While I'm not excited about the idea of manually converting everything over, I also wonder if having a mix of the two styles would become enough of an annoyance to be distracting. I think I could live with the mix for quite a while, but would like other opinions.

I think we should have a plan one way or the other before accepting the stylistic change.

As an aside, I think (and hope) it's an exaggeration to use words like "drowning" and "assault" is describing the current style. This issue reads more like an editorial than I think a task normally should.

I'd generally like to see a more balanced comparison of the options when they take the form of a redmine issue, in any situation where we are choosing from multiple options. There are reasonable, rational people who make the choice on each side, so let's take an objective look at why. I understand that this issue was filed as a proposal, so there is a natural element of advocacy for a particular choice. That is fine and productive. But that advocacy, when in the form of an issue to be worked on by an engineer, should be done in a balanced and objective way that considers each option seriously.

If you do feel strongly about something, and you want to write an editorial-style persuasive piece advocating for a particular choice, that's very valuable. But I think it should be separate from the body of a redmine issue. And even when you make a persuasive argument in other venues, consider that the use of hyperbole does not invite or promote the contribution of differing perspectives.

In this case, it's clear that most of us prefer the Google style, and that's great. Nobody has expressed that they dislike it, which is even better. I think we've arrived at a fine path forward, but I wanted to point this out for the benefit of future proposals.

mhrivnak wrote:

I'm happy accepting this as groomed once we answer just one more question: what will the transition be like?

Options:

• Use the new style when writing new doc blocks, and optionally when updating old ones. Otherwise leave old ones as-is.
• Spend (a lot of) time converting all doc blocks to the new style.
• Find or make a tool to automatically do much of the conversion.

Preferences? While I'm not excited about the idea of manually converting everything over, I also wonder if having a mix of the two styles would become enough of an annoyance to be distracting. I think I could live with the mix for quite a while, but would like other opinions.

I think we should have a plan one way or the other before accepting the stylistic change.

I converted many existing docstrings, though not to any accepted style, in https://github.com/pulp/pulp/pull/2789. It wasn't that much work, but was constrained to the ReST-style docstrings in the "pulp.app" namespace. So this is my preference:

• Spend (a lot of) time converting all doc blocks to the new style in new code.

As (maybe) expected, in order to not spend a lot of time converting all the existing docs, I took this approach:

• Find or make a tool to automatically do much of the conversion.

The gist is some (vim-style) regexen: %s/\(\s*\):param\s\+\(.*\):\s\+\(.*\)\n\s*:type\s\+.\+:\s\+\(.*\)/\1 \2 (\4): \3 to catch all the typed params, and s/\(\s*\):param\s\+\(.*\):\s\+\(.*\)/\1 \2: \3 for untyped.

This needs to be modified if other (typed or untyped) params exist, such as :ivar:/:vartype: combos. After running the regex, the only work left is pasting in the section headers (e.g. "Args:", etc.)

mhrivnak wrote:

As an aside, <snip>...
If you do feel strongly about something, and you want to write an editorial-style persuasive piece advocating for a particular choice, that's very valuable. But I think it should be separate from the body of a redmine issue. And even when you make a persuasive argument in other venues, consider that the use of hyperbole does not invite or promote the contribution of differing perspectives.

This is a valuable point, and maybe worthy of discussion on pulp-dev, and/or adapted to fit into our current "writing a story" docs[0]. I'm not sure how to track that, but at the very least I don't want this to be lost in the guts of a redmine issue.

[0]: http://docs.pulpproject.org/en/2.12/nightly/dev-guide/contributing/features.html?highlight=story#writing-a-story

We've identified this as a great opportunity to use a PUP for documenting the pros and cons of using Napoleon for formal acceptance by the team before adding its use to our dev docs.

This task is now up for consideration as a PUP. Other work is halted until PUP is approved.

Voting is scheduled to be finished on April 10. 2017.

https://github.com/pulp/pups/pull/2

https://github.com/pulp/pulp/pull/3035

https://github.com/pulp/pulp/pull/3055