René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Use the latest Sphinx version","articleBody":"# Documentation\r\n\r\nPython's documentation uses the Sphinx toolchain. Originally written for the Python documentation, it is now developed and distributed as an independent project. The two remain closely linked, e.g. when new syntax is added to the Python language. To document this syntax in the best way, Sphinx must support it and Python must require a version of Sphinx that supports the syntax.\r\n\r\nUsing the new syntax in PEP-695 as an example:\r\n\r\n1. The implementation was committed on 16 May (#103764)\r\n2. The first draft of the documentation was written on 19 May (#104642)\r\n3. A feature request was created in Sphinx on 23 May (https://github.com/sphinx-doc/sphinx/issues/11438)\r\n4. Sphinx added support on 23 July (https://github.com/sphinx-doc/sphinx/pull/11444)\r\n5. Sphinx published a release with support on 24 July ([v7.1.0](https://www.sphinx-doc.org/en/master/changes/7.1.html))\r\n7. The Python project can use those features, 19 October [+ 1 year] (#125368)\r\n\r\nThis is a ~two month window from implementation to support in a release of Sphinx. It took a further 15 months and two feature releases (3.12, 3.13) until these features can be used in Python. Due to this, our documentation is meaningfully worse for readers and programmers. Using older versions of Sphinx mean that we cannot succinctly cover the features and syntax that exist within released versions of Python.\r\n\r\nCore developers responsible for these features have [expressed](https://github.com/python/cpython/pull/104642#discussion_r1200799012) [interest](https://github.com/python/cpython/pull/123544#discussion_r1739933935), but have been hampered by our self-imposed restriction of the minimum version of Sphinx that we support.\r\n\r\nWe adopt these restrictions for the benefit of downstream Linux redistributors, as can be seen in the more recent issues in the summary table below. This has not always been the case. From the adoption of Sphinx in 2007 (8ec7f656134b1230ab23003a94ba3266d7064122 / 116aa62bf54a39697e25f21d6cf6799f7faa1349) until 2014 (f7b2f36f747179cf3dc7a889064f8979e3ad4dae), the latest source-tree checkout of Sphinx at https://svn.python.org/ was used. From then until ~2018 the minimum required Sphinx version (controlled by `needs_sphinx` in `conf.py`) tracked the latest release promptly. This has since ossified.\r\n\r\nIn a recent informal discussion, several committers supported the idea of removing or relaxing this restriction, allowing the Python documentation to use the latest version(s) of Sphinx. This is the context for this note, which for now **is a proposal**. The status quo will prevail if there is not sufficient support.\r\n\r\nAs a concrete suggestion, I propose that when evaulating increasing the minimum required version of Sphinx, we no longer consult downstream redistributors' Sphinx versions. The procedure will follow standard Python development processes in all other ways. I expect that the minimum version would be updated if and when a new Sphinx feature is of sufficient benefit to Python. This, though, may be a greater version than a downstream redistributor provides.\r\n\r\nWe would like to solicit views from representatives of downstream redistributors as to how (in)feasible this proposal would be. My understanding is that Fedora and SUSE have processes whereby a newer version of Sphinx can be used soley for the Python documentation. I do not know how this will impact Debian or Gentoo.\r\n\r\nThank you in advance for your consideration,\r\nAdam\r\n\r\n**Table of past changes to ``needs_sphinx``**\r\n\r\n| `needs_sphinx` | Issue     | PR / Commit                              | Latest Sphinx [^1] |\r\n| --             | --        | --                                       | --                 |\r\n| 7.2.6          | #125277   | #125368                                  | 8.1.3              |\r\n| 6.2.1          | #117928   | #121986                                  | 7.4.6              |\r\n| 4.2            | #109209   | #109210                                  | 7.2.6              |\r\n| 3.2            | #86986    | #93337                                   | 5.0.1              |\r\n| 1.8            | #80188    | #11887                                   | 1.8.4              | \r\n| 1.7            | [doc-sig] | #9423                                    | 1.8.1              | \r\n| 1.2            | #65630    | 90d76ca7657566825daf8e5b22ab011f70439769 | 1.2.3              | \r\n| 1.1            | #64860    | f7b2f36f747179cf3dc7a889064f8979e3ad4dae | 1.2.1              | \r\n\r\nPrevious discussion relating to the minumum version:\r\n\r\n* #84385\r\n* #87009\r\n* #104818 \r\n\r\ncc:\r\n\r\n* @doko42 @mitya57 / Debian\r\n* @hroncok / Fedora / RHEL\r\n* @mgorny / Gentoo\r\n* @danigm @mcepl / openSUSE\r\n* @AA-Turner @hugovk / CPython\r\n\r\n[^1]: At commit date.\r\n\r\n[doc-sig]: https://mail.python.org/pipermail/doc-sig/2018-September/004084.html\n\n\u003c!-- gh-linked-prs --\u003e\n### Linked PRs\n* gh-128922\n* gh-129037\n* gh-129038\n* gh-129039\n* gh-129041\n* gh-129042\n* gh-129277\n* gh-129278\n* gh-129279\n* gh-129306\n* gh-130444\n* gh-130858\n* gh-130859\n\u003c!-- /gh-linked-prs --\u003e\n","author":{"url":"https://github.com/AA-Turner","@type":"Person","name":"AA-Turner"},"datePublished":"2024-10-19T06:16:56.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":13},"url":"https://github.com/125722/cpython/issues/125722"}