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

Use Sphinx intersphinx or extlinks for common cross-refs, not full URLs #9081

Closed
3 tasks
Zac-HD opened this issue Sep 7, 2021 · 4 comments
Closed
3 tasks
Labels
type: docs documentation improvement, missing or needing clarification

Comments

@Zac-HD
Copy link
Member

Zac-HD commented Sep 7, 2021

Via #9041 (comment) - these changes make our docs easier to read in plaintext, and give us a single location to update if something we're referencing moves (e.g. the docs for an upstream package). Specifically, let's:

  • Ensure that we're using intersphinx for all our frequently-referenced docs
  • Check for manual links which could use intersphinx in CI
    (using something like @hoefling's special builder, which I want to copy for my projects)
  • Use extlinks for other patterns like Pytest issues and PRs

See sphinx-doc/sphinx#9626 for upstream progress on this; we'll adopt the checker once it's released by Sphinx ✨

@Zac-HD Zac-HD added the type: docs documentation improvement, missing or needing clarification label Sep 7, 2021
@nicoddemus
Copy link
Member

Just a note: see if it runs fast enough that we can include the check in pre-commit, instead of just the CI.

@Zac-HD
Copy link
Member Author

Zac-HD commented Dec 9, 2021

@hoefling - it looks like this is done, but you're the expert - should we close the issue? If not, what additional changes do you want to see?

@hoefling
Copy link
Member

hoefling commented Dec 9, 2021

@Zac-HD I think it can be safely closed. The only thing I was waiting for was the approval of sphinx-doc/sphinx#9626, but now I see that it got outdated. I have to rebase it onto mainline and ask @tkomiya for another review and whether it can still be included in Sphinx==4.4. The bump of Sphinx itself then is a different story and this issue is largely unaffected by that.

@Zac-HD
Copy link
Member Author

Zac-HD commented Dec 9, 2021

Thanks for all your work on this 💖

@Zac-HD Zac-HD closed this as completed Dec 9, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type: docs documentation improvement, missing or needing clarification
Projects
None yet
Development

No branches or pull requests

3 participants