Skip to content

Use canonical RFC Editor URLs independently of Docutils - #14689

Open
Darlokt wants to merge 5 commits into
sphinx-doc:masterfrom
Darlokt:fix-new-rfc-base
Open

Darlokt wants to merge 5 commits into
sphinx-doc:masterfrom
Darlokt:fix-new-rfc-base

Conversation

@Darlokt

@Darlokt Darlokt commented Sep 18, 2026 •

Copy link
Copy Markdown

Purpose

Hej,
this updates the :rfc: role to use the canonical RFC Editor URL.

https://www.rfc-editor.org/info/rfcNNNN/

I was double checking if #14681 was enough to really fix all CI, as mentioned in #14677 but with new changes landing in upstream Docutils, this was no longer true, so here now the fixes to the newest 4 CI failures.

Sphinx currently provides its own rfc_base_url but uses Docutils Inliner.rfc_url template for the remaining path.
This makes generated URLs depend on the installed Docutils version: released version uses rfc%d.html, while current Docutils development versions use rfc%d/.
So, the same Sphinx version can generate different RFC URLs depending only on the installed Docutils version.
Combining the new RFC Editor base URL with the template from a released Docutils version would also produce /info/rfcNNNN.html, which is not a valid RFC Editor URL.

To fix this cleanly and decouple Sphinx a bit, Sphinx now constructs the rfcNNNN/ portion itself. This keeps RFC URLs consistent across supported and development Docutils versions while continuing to respect the configurable rfc_base_url.

The default base URL is changed from
https://datatracker.ietf.org/doc/html/ to the canonical
https://www.rfc-editor.org/info/.

Focused regression tests cover plain RFC references, section anchors, empty anchors, custom base URLs, HTML output, and LaTeX output.
The environment version is incremented so existing cached doctrees are rebuilt with the new URLs.
The declared docutils>=0.21,<0.23 dependency range is unchanged.

References

AI Disclosure

OpenAI Codex assisted with reviewing the implementation, analyzing compatibility with released and development Docutils versions. All AI-assisted work was reviewed and understood by me.

Bump ENV_Version to 67 to invalidate cached build environments.
@Darlokt

Darlokt commented Sep 19, 2026

Copy link
Copy Markdown
Author

The failures are flakey tests and the missing changes from #14681. I keep them separate, as they solve different issues, merging the two would resolve the Docutils HEAD failures and the LaTeX failures.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Use canonical URL for RFCs

1 participant