We are doing a new `/doc` endpoint where we list all the models, their fields, their public methods.

For every public method we list the parameters, their type, their default value and a help message.

We also provide with actual *runnable in the browser* examples how to call those methods in RPC.

The problem is that we fail to parse the docstring in far too many functions, because the rst is broken, or because not all parameters are correctly documented.

So, because we are very sane people, we decided to...

![image](https://github.com/user-attachments/assets/ec56617c-f3ee-4b47-891a-724382e86187)

(plus it makes for an excellent thing to talk about on Friday :smiling_imp:)

### Fix all `:param:` found in docstring

**Typo in parameter name**

```py
def foo(self, bar):
    """
    :param baz: blablabla
    """
```

**Malformed tag**

```py
""":param: baz blablabla"""
```

**Inconsistent type**

```py
def foo(self, bar: int | float):
    """
    :param int bar: blablabla
    """
```

**Bogus `**kwargs`**

We also noted several functions that are abusing `**kwargs` but actually document a bunch of parameters. We decided not to lint those, and to only emits a logging.info. I wish to change them someday.

```
def foo(self, **kwargs):
    """
    :param bar: blablabla
    :param egg: blablabla
    :param spam: blablabla
    """
```

There are also other mistakes we fixed, just read the commit n°2

### reStructuredText syntax error

While working on the first linter, we had to silence the docutils parser because it emitted too many warnings for badly structured rst.

The commit n°3 enabled those warnings and it reported several hundreds of broken docstrings.

With commit n°4 we decided on a per-module approach, starting with base (and base-inherited models), because there were damn too many docstrings to fix.

The common mistakes were:

**Missing empty line before list**

```rst
Items:
- one
- two
```

instead of

```rst
Items:

- one
- two
```

**Indented list**


```rst
Items:

  - one
  - two
```

instead of

```rst
Items:

- one
- two
```

**Bad code block**

```rst
:return: a list in the form
    {
        "a": 1,
    }
```
instead of either
```rst
:return: a list in the
  form::

    {
        "a": 1,
    }
```
or
```rst
:return: a list in the form
  ::

    {
        "a": 1,
    }
```

---

## Review

I had to decide on a few short-coming to get to a point where I can merge something. e.g. I stopped to care about changing `see the method create` to `see :meth:create`, or to surround technical terms (e.g. parameters) with a literal (double backtick).

If you wanna change stuff, just get in touch with me and please commit directly on-top of the branch with your changes.

Online rst editor: https://rsted.info.ucl.ac.be/
A script I made: https://gist.github.com/Julien00859/822835b0c75e8bfe0e1c003a32c029d2