[Doc] Style of parameter tables in API reference is being broken

[i-aki-y]

📚 Documentation

The style of the parameter tables in the API documentation is being broken.
https://albumentations.ai/docs/api_reference/augmentations/transforms/

I found recent commit inserts ------ in the docstrings:

    Args:
+    ----
	para1: ...
	para2: ...

This appears to prevent mkdocs from parsing the docstring, since mkdocs assumes "google-style" that does not use ----- for sections.

https://github.com/albumentations-team/albumentations.ai/blob/4fda83887b102ea3f0e08c9f10e5ea7d4dfd4201/mkdocs/src/mkdocs.yml#L13-L14

cf: about google-style
https://mkdocstrings.github.io/python/usage/docstrings/google/
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

[ternaus]

Thanks for pointing this out.

[ternaus]

FIxed in #1556

The issue was that script that generated docs did not distinguish between Deprecated class and deprecated parameter in the class and did not use it.

[i-aki-y]

@ternaus Thank you for your quick response.

But I could not confirm the fix in the documetation site.

Lines "----" appear in commit #1529, where the lines are inserted at some sections (not all sections) of every transform's docstrings.
I think we need to remove those inserted lines “----" to fix the issue.

[ternaus]

I was not able to set up ruff to check for "----", it does not flag it as violation of google docstrings format.

I will try to upgrade version of mkdocs, maybe it will be more robust toward formatting of the docstring.

I can also have a custom hook, that just look for "---" and longer in the code.

What exactly don't you like in the existing version of parsed docstrings?

[i-aki-y]

The current albumentation dosctring mixes two docstring section styles (google and numpy).
The mkdocs support two of them but can not handle mixed cases in a single project.
I found the following issue discussing more flexible style support in the mkdocs, but the issue is still open and is inconclusive.

mkdocstrings/griffe#5

It would be preferable to format docstring with tools like ruff or black, but currently, they do not seem able to handle docstring styles.
And I could not find other tools that support formatting multiple docstring styles.

If possible, I think writing a custom hook would be a practical workaround, and I expect deleting "---" is sufficient.
I could confirm that the mkdocs correctly rendered the parameter table by deleting lines "----" in a transform docstring on my local machine.

Ex:

[ternaus]

Added check for --- in docstrings and cleaned from the existing code. It is a hack, rather than solution, but hopefully will help for some time: #1558

[ternaus]

Looks like works

[i-aki-y]

@ternaus Thanks!