Justification for enquoting parameters in single backticks
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
https://numpydoc.readthedocs.io/en/latest/format.html#parameters states
Enclose variables in single backticks.
e.g.
x : type
Description of parameter `x`.
Is there a specification backing this format? I have not found single backticks as valid markup in sphinx or docutils documentation. In contrast if using a default role in sphinx, this generates warning that the role traget cannot be resolved.
While that may (or may not)* work for numpy specifically, it can be a source of confusion for other projects that adopt the numpydoc style. It should at least be mentioned that single backticks can cause trouble with the default_role.
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
Read the numpydoc Parameters guidance and the linked Sphinx default_role documentation, then compare the single-backtick recommendation with the reported warning. Done means reaching a project decision on whether the guidance needs clarification and identifying the documentation change required.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100