Support cython embedSignature

[multimeric]

Is your feature request related to a problem? Please describe.
When using cython with the embedSignature option, the __doc__ of the function will have the function signature in the first line of the doc. This naturally results in confusing documentation downstream in mkdocs because the signature gets repeated and presented incorrectly.

Describe the solution you'd like
I propose adding a new setting to all (?) docstring parsers along the lines of cython_embed_signature: bool, which, if true, will strip the first line from the docstring prior to parsing, and use it as the function signature instead of however it is done now.

Describe alternatives you've considered

• Using show_signature: False improves the current documentation somewhat, but the signature is still formatted incorrectly.

Additional context

• https://cython.readthedocs.io/en/latest/src/userguide/source_files_and_compilation.html#:~:text=Default%20is%20True.-,embedsignature,-(True%20/%20False)
• https://stackoverflow.com/questions/50492949/how-to-display-the-arguments-of-a-cython-function-in-the-documentation

[pawamoy]

Interesting, thanks for the request 🙂

So, we already have the ignore_init_summary option. I guess you'd like to have this for any function.
Additionally, you'd like to use the embedded signature instead of the inspected one... not sure if that's possible 🤔
At least not easily.

I'd like to see an example of such rendered signatures + docstrings, could you show us that? A screenshot of your localhost:8000 docs would be just fine.

[multimeric]

Yeah sure, it looks like this (with show_signature = true):

[tazend]

Hi,

working on the Cython project that sparked this issue and just wanted to give an update.

Instead of the embedSignature functionality in Cython, we moved to the latest Cython 3.0 version for generating documentation. Cython 3.0 is still in a Beta state, but has much better support that allows for proper introspection (e.g. correctly preserving function signatures)

So with that, the documentation basically renders as expected, and I'd say if implementing special support for the embedSignature functionality is too much work, its not really worth looking into it considering you can just use Cython 3.0 to compile your project for the purpose of generating the docs.

The only caveat I noticed is that Cython is not able to preserve the function signature of special methods, for example __init__ (cython/cython#3873 (comment))
So the parameters still show up in the documentation, but griffe generates a warning that the parameter is missing from the signature (rightfully so) and the parameter is marked as required (even though it technically isn't)

So the only way to allow for displaying a default value would be to extract it directly from the parameter in the docstring.
I made a quick fix that allows for specifying such a default value in the google docstring format after the optional statement, so you could do something like:

Args:
     myparam (int, optional=10): My param

Although I'd understand if you wouldn't want to include this functionality, since its a special fix and not really part of the google docstring syntax (not sure if numpy or sphinx would allow for something like this already). But I just wanted to share what I found out :)

EDIT: An additional drawback however regarding __init__ is that you also don't get a signature rendered in the docs.

[pawamoy]

Hey @multimeric, @tazend. I have looked at this again and decided to close as out of scope. Cython 3.0 seems to resolve most of the issue, leaving only __init__ method signatures to be improved. Griffe supports introspection of objects, so frameworks that build such Python objects should do it in a way that conforms with what introspection tools expect (Python objects looking like real Python objects and providing correct metadata).

Adding an option to consider the first line of a docstring to be a signature that should be parsed again and used instead of the real signature feels a bit heavy. Docstring styles are already quite complicated to support (their specs are generally under specified), so adding more custom logic is not appealing to me 😅

If we ever want to be able to specify default values in docstrings, it would have to re-use Python syntax (as it's the only way to parse it correctly in 100% of cases without having to re-implement a custom parser ourselves), something like:

def __init__(self):
    """Summary.

    Parameters:
        param1: str | int = 0
            Description of param1.
        param2: list[Class] | None = None
            Description of param2.
    """
    ...

...but this should be discussed in another issue, for example in this one: mkdocstrings/mkdocstrings#577 🙂