Support Epytext docstring syntax (`@param`)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.5k
- Forks
- 228
- PR merge metrics
- No merged PRs in 30d
Description
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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating pdoc's docstring parsing code and the existing handling for Google and numpydoc formats. Read issues #143 and #153 for related context, then verify that both :param <param-name>: and @param <param-name>: forms are recognized and rendered as parameter documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100