sphinx-doc / sphinx-doc/sphinx
ref role should capitalize in man output
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Is your feature request related to a problem? Please describe.
The man page write capitalizes the section headings but doesn't capitalize the
references. Take this short document for example (assume sphinx.ext.autosectionlabel is
enabled):
mini
####
Synopsis
========
| :program:`mini`
Description
===========
See :ref:`mini:Synopsis`
It turns into
As you can see the reference to Synopsis is not capitalized.
Describe the solution you'd like
It would be nice if it was automatically capitalized in the man output. This makes it clear that it is actually a reference to a section heading, as italics can mean many things in a man page, not just section headings.
Describe alternatives you've considered
I've considered regular old mdoc(7) for writing man pages. It correctly
capitalizes references. However, it is more esoteric and generally less
extensible than reST.
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 with the man-page writer and its handling of :ref: targets, using the example with sphinx.ext.autosectionlabel as the reproduction case. Check the generated man output for a capitalized “Synopsis” reference; done means section-heading references are capitalized without changing other man-page text.
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
- 48/100