Consistent docstring formatting

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?


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.

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

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

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

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.