Skip to content

Restore Sphinx manpage reference rendering with Docutils 0.22#14436

Open
Mirochill wants to merge 1 commit into
sphinx-doc:masterfrom
Mirochill:fix-14427-manpage-references
Open

Restore Sphinx manpage reference rendering with Docutils 0.22#14436
Mirochill wants to merge 1 commit into
sphinx-doc:masterfrom
Mirochill:fix-14427-manpage-references

Conversation

@Mirochill
Copy link
Copy Markdown

@Mirochill Mirochill commented May 18, 2026

Summary

  • restore Sphinx's custom manpage reference renderer after Docutils 0.22 installs an instance-level visit_reference
  • preserve the historical reference styling tuple when newer Docutils versions no longer expose it
  • add a regression test for :ref: and :doc: rendering in man pages

Root cause

Docutils 0.22 assigns visit_reference on the manpage translator instance according to its text_references setting. That shadows ManualPageTranslator's specialized Sphinx implementation, so internal references render as raw <uri> fragments such as <#other-ref> and <> instead of styled text.

Fixes #14427.

Validation

  • Not run locally
  • relying on the repository's GitHub Actions / Read the Docs checks for remote validation

@Mirochill Mirochill force-pushed the fix-14427-manpage-references branch from c27afca to b24d491 Compare May 18, 2026 15:43
@Mirochill Mirochill marked this pull request as ready for review May 18, 2026 16:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bad references in man pages

2 participants