sphinx-doc / sphinx-doc/sphinx
Untangle Roles and Cross-referencing syntax docs
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
From: https://github.com/sphinx-doc/sphinx/pull/12944#discussion_r1786968351
There's a certain overlap between Cross-referencing syntax and Roles.
The following roles are essentially cross-links but are only mentioned in "Roles": :manpage:, :pep:, :rfc:, :cve, :cwe:
Possible solution: Move them from "Roles" to "Cross-referencing syntax" and mention them in https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax.
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
Compare the Cross-referencing syntax and Roles pages linked in the issue, focusing on :manpage:, :pep:, :rfc:, :cve:, and :cwe:. Move or cross-reference the relevant explanations so the roles are documented with other cross-links without duplication, then build the documentation and check both sections.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100