Consistent docstring formatting

Development
#1

I wanted to ask what if anything the Pulp conventions for docstings are?

I have a vague memory of someone pointing me at Example Google Style Python Docstrings — napoleon 0.7 documentation in the past, but I am not sure if this is an official convention. I believe I have seen different styles for docstrings when I look over the various Pulp repositories.

I suppose the only way to become truly consistent with docstrings would be to use a linter/formatter. A colleague has suggested docformatter · PyPI might be worth exploring.

The main purpose of this post is to gauge where everyone is at before I invest time into the wrong direction. Your thoughts?

3 Likes
#2

I believe it is valuable to have a shared expectation of what a docstring is supposed to look like. I see a shared written convention as the second step; and enforcing it using GHA/GitLab build the third step.

#3

In pulp CLI/glue we use https://mkdocstrings.github.io/ to generate the reference docs. The types are drawn from the type annotations directly there. So the format is already different by nature.

#4

So does mkdocstrings force you to create docstrings in a praticular format somehow?

#5

I guess everything that mkdocstrings-python understands would render. See:

https://mkdocstrings.github.io/griffe/docstrings/

#6

The Google Style is recommended in the pulpcore style guide.

I like this convention and that’s probably the most used one (in pulp).
Nevertheless, as we are moving away from sphinx we should take some details about it:

  • How to write link to other code objects
    • needs some testing because of the aggregation process in the new docs.
  • How to handle typing
    • as Matthias mentioned, mkdocstrings infers type-annotations, so it may be omitted if types are being used.
  • Write as markdown in general, not rst (again, for the docs render).

I’m not sure we’ll find a linter capable of checking all these details, but even some basic Google-Style and spacing would already help a lot with consistency.

3 Likes
#7

I did some experiment on this: https://github.com/pulp/pulpcore/pull/6605

TLDR:

  1. docformatter can do some general formatting but it isnt good at enforcing dostring style
    • This can be configured to conform to the “prevalent standards” and reduce the amount of changes, although I like the compact way it looks by default.
  2. looked at some alternatives and the most promissing is pydoclint, which has better capabilities of checking style.

Do we wanna go on with this? We could only do (2), or do both (1) and (2).
I liked docformatter, even though it doesnt meet this specific goal.

A bit orthogonal, but this makes me think we could setup a pre-commit + makefile runner on plugin_template. The pre-commit should help on having a consistent setup of the tooling versions locally and on CI (I dont mean to use the git hooks, it has a manual mode), and the makefile abstract all the specific tooling (currently flake8+black, but if we do this we’ll possibly add other(s)).

3 Likes