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