Support Epytext docstring syntax (`@param`)

[thehale]

Problem Description

As noted in #143 , many Python projects use the format :param <param-name>: <description> or @param <param-name>: <description>, but this format for documenting function parameters is not recognized by pdoc.

Proposal

I would love to see pdoc add support for these formats for documenting function parameters. I work with several projects that use this format. Additionally, I feel like this format looks better in the code (particularly inside of IDE help texts).

Alternatives

Converting these docstrings to the google or numpydoc formats described in #153 is burdensome for larger projects that want to switch to using pdoc, especially since pdoc otherwise works so beautifully out of the box.

Additional context

n/a

[mhils]

Is there a name for that format? Is that Epytext? If this is remotely standardized and not completely homegrown I'd be happy to merge a PR that adds support for it. :)

If you (or anyone else) wants to contribute this, I'm happy to rig it up with the rest of pdoc.

[loldebyte]

The @param synthax is indeed Epytext, but the :param <param_name>: one is reST as used by Sphinx so i guess it is pretty structured.
That docstring format is also the default for Jetbrains' Pycharm.

[mhils]

Quick update: pdoc now supports :param <param_name>: declarations (#369). 😃 If someone wants to contribute epytext I'm happy to guide them, but I think the Sphinx syntax covers the majority of use cases.

[gerardsimons]

So :returns: are not yet supported?

[mhils]

:return: should work just fine. Is :returns: a standard thing? That would be trivial to add here if it is.

[gerardsimons]

Oh lol, it's supposed to be :return:! Works like a charm :-)

[savchenko]

Apologies for interrupting the thread, but this doesn't seem to work.

Test code

def random_ascii(length: int = 32) -> str:  # {{{
    """
    Return a random string of ASCII letters and digits.

    :param length: Length of the random string.
    :return: Random ASCII string.
    """
    return "".join(choices(ascii_letters + digits, k=length))  # }}}

Rendered documentation

pdoc v15.0