Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sphinx setup should be stricter #2424

Closed
webknjaz opened this issue Oct 15, 2020 · 3 comments · Fixed by #2427
Closed

Sphinx setup should be stricter #2424

webknjaz opened this issue Oct 15, 2020 · 3 comments · Fixed by #2427

Comments

@webknjaz
Copy link
Member

I noticed that some of the docs pages are unreachable when navigating from the main RTD page. In particular, I know that there's history.rst that is only accessible if one knows the URL upfront.

I tracked this to #2097 which removes entries from the TOC but doesn't reintroduce them in other places.

Sphinx has a few toggles that make it nitpicky about warnings. I think this should be enabled in the CI to prevent such problems in the future. This should catch implicit orphan pages as well as dead references or typos.

@alvyjudy
Copy link
Contributor

alvyjudy commented Oct 15, 2020

I take the blame for a lot of breaking links as I ran out of steam in the middle of the docs revamp. I think jaraco felt that the halfway efforts still made a readable documentation and decided to merge them anyways, and fix the issues subsequently. See here for the context

I do plan on making more changes here and there to fix those issues and am happy to see the doc is receiving more supports and attention:)

@webknjaz
Copy link
Member Author

@alvyjudy please hold on with your PRs. I've got a huge change fixing many refs and enforcing the checks incoming. Let's merge it first so that the CI would verify any further changes automatically.

webknjaz added a commit to webknjaz/setuptools that referenced this issue Oct 15, 2020
webknjaz added a commit to webknjaz/setuptools that referenced this issue Oct 15, 2020
@webknjaz
Copy link
Member Author

Here you go: #2427.

webknjaz added a commit to webknjaz/setuptools that referenced this issue Oct 15, 2020
webknjaz added a commit to webknjaz/setuptools that referenced this issue Oct 17, 2020
This change makes the RTD config documented more explicitly and
migrates away from the legacy v1 schema.

Among other things, it enables Sphinx strict mode on RTD to support
the goal of pypa#2424.

It also switches the builder to `dirhtml` that resolves pypa#2432.
webknjaz added a commit to webknjaz/setuptools that referenced this issue Oct 17, 2020
This change makes the RTD config documented more explicitly and
migrates away from the legacy v1 schema.

Among other things, it enables Sphinx strict mode on RTD to support
the goal of pypa#2424.

It also switches the builder to `dirhtml` that resolves pypa#2432.
webknjaz added a commit to webknjaz/setuptools that referenced this issue Oct 19, 2020
This change supports the goal of
pypa#2424.
webknjaz added a commit to webknjaz/setuptools that referenced this issue Dec 21, 2020
This change supports the goal of
pypa#2424.
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 a pull request may close this issue.

2 participants