Support Epytext docstring syntax (`@param`)

mitmproxy / pdoc

API Documentation for Python Projects

https://pdoc.dev

MIT No Attribution

1.98k stars 196 forks source link

Support Epytext docstring syntax (`@param`) #275

Open thehale opened 3 years ago

thehale commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 2 years ago

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 commented 2 years ago

So :returns: are not yet supported?

mhils commented 2 years ago

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

gerardsimons commented 2 years ago

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

savchenko commented 5 days ago

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