Task: refactor docs or decide not to uses sphnix docs format for CLI

[MVrachev]

What is the task about?

While working on an issue while building the docs I got the error:

rstuf/cli/repository_service_tuf/helpers/cli.py:docstring of repository_service_tuf.helpers.cli.calculate_blake2b_256:4:Field list ends without a blank line; unexpected unindent.

I looked at the code and I noticed we are using a different style for our docs there and it seems that it's the sphnix
docstring format: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#the-sphinx-docstring-format
The error I got was not in any way connected to the code I touched.
The function where I got the error is:

repository-service-tuf-cli/repository_service_tuf/helpers/cli.py

Line 51 in 1bb44e3

def calculate_blake2b_256(filepath: str) -> str:

When I decided to experiment by removing the :param from the filepath docstring documentation I noticed that other functions in this file had the same problem.

I want to ask what the other maintainers think: do we want to use the sphnix docs?
If so, let's use this issue to remind us to propose a pr adding the same format at the other files as well.
What do you all think: @kairoaraujo @KAUTH?

PS: The solution for this concrete error is to make each parameter doc to be one-line:
https://stackoverflow.com/a/63599880

Code of Conduct

• I agree to follow this project's Code of Conduct

[kairoaraujo]

I want to ask what the other maintainers think: do we want to use the sphnix docs? If so, let's use this issue to remind us to propose a pr adding the same format at the other files as well. What do you all think: @kairoaraujo @KAUTH?

We do use sphinx docs.
It is in our documentation structure. Check out our development documentation strucutre.

So, it builds our documentation specifics for CLI.
Which is rendered on https://repository-service-tuf.readthedocs.io/projects/rstuf-cli/en/latest/devel/, in that case, more specifically on the https://repository-service-tuf.readthedocs.io/projects/rstuf-cli/en/latest/devel/#component-level with all the implementation.

Basically we have one unique documentation.

[MVrachev]

This means that we need to use the :param prefix when documenting our attributes.
See: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#the-sphinx-docstring-format
We don't do that and sphnix doesn't complain because of that for multi-lines documented parameters.