GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-104818: Require Sphinx 6.2 to build the doc by vstinner · Pull Request #104819 · python/cpython

Conversation

@vstinner

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

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member
  • Issue: Require Sphinx 6.2 to build Python 3.13 documentation #104818

📚 Documentation preview 📚: https://cpython-previews--104819.org.readthedocs.build/

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@vstinner
vstinner requested review from ezio-melotti and hugovk as code owners May 23, 2023 20:45
@bedevere-bot bedevere-bot added the awaiting core review label May 23, 2023
@bedevere-bot bedevere-bot mentioned this pull request May 23, 2023
Require Sphinx 6.2 to build Python 3.13 documentation #104818
Closed
zware
zware approved these changes May 25, 2023
View reviewed changes
Comment thread Doc/conf.py Resolved

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-bot bedevere-bot added awaiting merge and removed awaiting core review labels May 25, 2023
vstinner added 2 commits May 25, 2023 20:44
@vstinner
pythongh-104818: Require Sphinx 6.2 to build the doc
acc5c47
@vstinner
Elaborate comments
9d8ff71
Also document the build requirements in Doc/using/configure.rst
@vstinner
vstinner force-pushed the sphinx62 branch from d6f3eaa to 9d8ff71 Compare May 25, 2023 18:47
@vstinner
vstinner requested review from corona10 and erlend-aasland as code owners May 25, 2023 18:47
@vstinner
Fix requirements-oldest-sphinx.txt
b645426
I really want Sphinx 6.2.0, not Sphinx 6.2.1.
@vstinner

vstinner commented May 25, 2023

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.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

zware
zware reviewed May 25, 2023
View reviewed changes
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.

@zware zware May 25, 2023

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@CAM-Gerlach CAM-Gerlach May 25, 2023 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@hugovk hugovk May 26, 2023

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

erlend-aasland reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

@vstinner vstinner May 26, 2023

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@CAM-Gerlach CAM-Gerlach May 27, 2023

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@vstinner

vstinner commented May 26, 2023

Copy link
Copy Markdown
Member Author

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

zware and hugovk reacted with hooray emoji
All reactions
  • 🎉 2 reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner vstinner closed this May 26, 2023
@vstinner
vstinner deleted the sphinx62 branch May 26, 2023 13:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@zware zware zware approved these changes
@CAM-Gerlach CAM-Gerlach CAM-Gerlach left review comments
@ezio-melotti ezio-melotti Awaiting requested review from ezio-melotti ezio-melotti is a code owner
@hugovk hugovk Awaiting requested review from hugovk hugovk is a code owner
@erlend-aasland erlend-aasland Awaiting requested review from erlend-aasland erlend-aasland is a code owner
@corona10 corona10 Awaiting requested review from corona10 corona10 is a code owner

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

awaiting merge

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

5 participants

@vstinner @hugovk @zware @CAM-Gerlach @bedevere-bot
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.