Iris API param not rendering

[tkknight]

📚 Documentation

Whilst reviewing the dsocs for another task I noticed there are a few occurrences of :param: that is not rendering correctly due to alignment and maybe other syntax issues.

• https://scitools-iris.readthedocs.io/en/latest/generated/api/iris/fileformats/pp.html?highlight=%3Aparam%3A#iris.fileformats.pp.save
• https://scitools-iris.readthedocs.io/en/latest/generated/api/iris/fileformats/nimrod_load_rules.html?highlight=%3Aparam%3A#iris.fileformats.nimrod_load_rules.run
• https://scitools-iris.readthedocs.io/en/latest/generated/api/iris/fileformats/dot.html?highlight=%3Aparam%3A#iris.fileformats.dot.save

There maybe other occurrences too, not dug any further.

[trexfeathers]

I didn't even know that was supposed to be possible! Would be great if it worked 🙂

[pp-mo]

It definitely does work in many places.
For example : https://scitools-iris.readthedocs.io/en/latest/generated/api/iris/coords.html#iris.coords.CellMethod.method
which comes from : https://github.com/SciTools/iris/blob/main/lib/iris/coords.py#L2974-L2975

However, I'm seeing that some other things are not so happy..
Sphinx seems to have started putting two of these on one line sometimes. #4660
Which may or not be related..

[vsherratt]

The consistent thing between those examples is that they are formatted like

Args:
    * something - description

which is probably a few too many steps away from what napoleon expects. I would try:

• removing the * list markers
• removing the indentation
• replacing the - with :

[tkknight]

I have a branch primed to fix this issue but ideally want to use my read the docs test space to render them for all to see, thish is being used for another PR atm. Will create the PR next week sometime.

Related to #3840.

[tkknight]

Fixed by #3840.