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

[docs] [docs infra] Finish Sphinx migration #37944

Closed
angelinalg opened this issue Jul 31, 2023 · 2 comments · Fixed by #41115
Closed

[docs] [docs infra] Finish Sphinx migration #37944

angelinalg opened this issue Jul 31, 2023 · 2 comments · Fixed by #41115
Assignees
Labels
docs An issue or change related to documentation P1 Issue that should be fixed within a few weeks

Comments

@angelinalg
Copy link
Contributor

Description

The Sphinx migration has been started but it needs to be completed. #35073
cc: @max

Link

No response

@angelinalg angelinalg added P1 Issue that should be fixed within a few weeks docs An issue or change related to documentation labels Jul 31, 2023
@peytondmurray
Copy link
Contributor

peytondmurray commented Aug 24, 2023

I'm working on this in stages so the PR doesn't get overwhelming, and because there's a couple of different things we need to to make the Sphinx upgrade smooth. I'll add to this checklist as I go:

  • Remove unnecessary doc dependencies. External modules for which documentation isn't being hosted shouldn't need to be installed to build the docs (e.g. tensorflow, torch, etc should be mocked out with autodoc_mock_modules)
  • Attempt an upgrade to the latest version of Sphinx and all Sphinx-related dependencies. The docs will likely be broken/look very different due to changes in pydata-sphinx-theme and sphinx-book-theme. Determine the work needed to get the docs into a presentable state given the new styles.

@peytondmurray
Copy link
Contributor

peytondmurray commented Sep 29, 2023

A few more todo items:

  • We are dropping sphinx-external-toc, so there are a bunch of orphaned pages; we need to build a new toctree with these pages included to be displayed at the landing page for the docs.
  • Move the CSAT widget out of a custom template. There's a pydata-sphinx-theme layout guide that shows where different things can be placed; the HTML for this can just be put in the sphinx configuration instead.
  • Sort out syntax highlighting. In addition to pygments, we are also loading highlight.js in multiple places - without extra work highlight.js will not work for dark/light theme switches.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs An issue or change related to documentation P1 Issue that should be fixed within a few weeks
Projects
None yet
2 participants