FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gh-104818: Require Sphinx 6.2 to build the doc by vstinner · Pull Request #104819 · python/cpython · GitHub

/ cpython Public

gh-104818: Require Sphinx 6.2 to build the doc - #104819

Closed
vstinner wants to merge 3 commits into
python:mainfrom
vstinner:sphinx62
Closed

gh-104818: Require Sphinx 6.2 to build the doc#104819
vstinner wants to merge 3 commits into
python:mainfrom
vstinner:sphinx62

Conversation

vstinner commented May 23, 2023
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Member

Comment thread Doc/conf.py
vstinner added 2 commits May 25, 2023 20:44
Also document the build requirements in Doc/using/configure.rst
I really want Sphinx 6.2.0, not Sphinx 6.2.1.

Copy link
Copy Markdown
Member Author

I modified the PR to require strictly Sphinx 6.2.0 in Doc/requirements-oldest-sphinx.txt, rather than Sphinx 6.2.1, since they are requirements to get the oldest supported Sphinx version.

Comment thread Doc/using/configure.rst

* On Windows, Microsoft Visual Studio 2017 or later is required.

* Sphinx 6.2 or newer is required to build the Python documentation.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

This seems a bit out of place here to me, but I don't have a better suggestion for where to put it off the top of my head. Do we actually mention building the documentation elsewhere in the docs? I can't find one with a short search.

CAM-Gerlach May 25, 2023
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Yeah, I agree—it seems quite out of place here. The meta-documentation for the docs themselves lives in the devguide, and this mention should presumably go there under the appropriate section.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I'd prefer to avoid mentioning the Sphinx version in the devguide and needing to keep it in sync. It's defined in the requirements.txt so whatever is needed will be installed as required. Plus it's different for older branches.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Are you saying that the whole section "Build Requirements" is irrelevant in Python documentation. Or that mentioning the minimum Sphinx version in "Build Requirements" is irrelevant?

For me, it's convenient to have the same repository where we actually specify needs_sphinx (Doc/conf.py) and we clearly document that version. Having two Git repositories just make it less pratical.

Do we actually mention building the documentation elsewhere in the docs?

I added this section recently. I wrote "Sphinx 6.2 or newer is required to build the Python documentation." If someone doesn't care about the doc, this sentence can be ignored.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I'd prefer to avoid mentioning the Sphinx version in the devguide and needing to keep it in sync. It's defined in the requirements.txt so whatever is needed will be installed as required. Plus it's different for older branches.

FWIW, on second thought I agree, and in fact it was I that removed the references to such recently when overhauling the section I linked. We could mention the files the requirements are defined in, though, and directly link them with the :cpy-file: role. That would allow users to easily check the versions for their desired branch without having to duplicate them multiple places, which will inevitably get out of sync.

Copy link
Copy Markdown
Member Author

I don't need to upgrade Sphinx anymore: #104818 (comment)

vstinner closed this May 26, 2023
vstinner deleted the sphinx62 branch May 26, 2023 13:34
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
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.

5 participants


Back | FazBrowse Home | New Git URL