request: harmonise docstrings

[nelimee]

Contributor License Agreement (CLA) signature

• A CLA signature is requested for any first contribution. Further information can be found in our contributing guidelines.

Motivation

The different deltakit sub-packages come from different sources that had different standards w.r.t., docstring formatting.

Docstrings should follow a unique and well-defined formatting standard all across the deltakit code base.

Proposed solution

Use the Google Sphinx style without types in docstrings (because we require correct typing, so the types in docstrings are duplicated information that will eventually be outdated).

• Use automated tools in CI that check that docstrings are correctly formatted.
• Add these tools to the pre-commit environment.

Among the interesting tools:

• ruff check with a well defined set of pydocstyle rules enabled repository-wide, with exclusions being explicitly justified and on a per-file granularity or lower.
• https://github.com/jsh9/pydoclint with the choosen style.

Potential alternatives

No response

Additional context

No response

[Shanwis]

I would like to work on this issue.

[nelimee]

Hi @Shanwis! We are working on a pretty large refactor of some parts of deltakit at the moment. To avoid you working on something that might be deprecated later, here are some of the areas that will not be touched too much by the refactor:

• deltakit-core,
• the "analysis" and "plotting" parts of deltakit-explorer and deltakit-decode (computing logical error probability, plotting, visualisation of decoding graph, ...).

You are welcomed to work on these parts. Try to not work on other parts, as they might be changed soon.

[Shanwis]

Ok, thank you for the heads up!