docs: switch documentation hosting from RTD to GitHub Pages#1411
docs: switch documentation hosting from RTD to GitHub Pages#1411vprusso merged 24 commits intovprusso:masterfrom
Conversation
- Build Sphinx documentation using uv-managed environment - Deploy generated HTML to the gh-pages branch - Add GitHub Pages workflow alongside existing RTD setup docs: allow GH Pages workflow to run on feature branch docs: run build via uv env
There was a problem hiding this comment.
Pull request overview
This PR migrates the toqito documentation hosting from ReadTheDocs to GitHub Pages by introducing a new GitHub Actions workflow. The migration aims to improve documentation appearance and functionality while maintaining the existing ReadTheDocs setup for independent review.
Changes:
- Adds
.github/workflows/docs.ymlto build Sphinx documentation and deploy to GitHub Pages - Configures automated deployment on pushes to master branch and docs changes
- Uses the project's standard
uvtool with thedocsdependency group for building documentation
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - master | ||
| - docs/gh-pages-switch |
There was a problem hiding this comment.
Inconsistent indentation. There is extra whitespace before 'master' that is not present in other workflow files. The hyphen should be followed by a single space, not multiple spaces. This should be '- master' changed to '- master' for consistency with YAML formatting conventions.
| - master | |
| - docs/gh-pages-switch | |
| - master | |
| - docs/gh-pages-switch |
|
|
||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@v4 |
There was a problem hiding this comment.
The action version should be updated to match the convention used in other workflows. All other workflows in this repository use actions/checkout@v6, but this workflow uses v4. Update to v6 for consistency.
| uses: actions/checkout@v4 | ||
|
|
||
| - name: Set up Python | ||
| uses: actions/setup-python@v5 |
There was a problem hiding this comment.
The action version should be updated to match the convention used in other workflows. All other workflows in this repository use actions/setup-python@v6, but this workflow uses v5. Update to v6 for consistency.
| - name: Install uv | ||
| run: pip install uv |
There was a problem hiding this comment.
The uv installation method should be updated to match the convention used in other workflows. All other workflows in this repository use astral-sh/setup-uv@v5 instead of pip install uv. This is more reliable and follows the recommended practice for GitHub Actions. Replace this step with the action used in other workflows.
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
|
@manasa-manoj-nbr it looks like you likely used AI to gen the docs build. This is fine, but it tends to use outdated versions of things (which it did here). Also your PR still has all of the RTD stuff present (which we discussed that we wanted to remove). Additionally, do you have any screenshots or test build links to showcase that this workflow actually generated the docs? |
Co-authored-by: Copilot <[email protected]>
|
On ReadTheDocs: I did that intentionally as an intermediate step so the GitHub Pages deployment could be reviewed and validated first. Based on your comment, I can remove the RTD configuration in this PR or follow up immediately with a cleanup commit. For verification: the workflow does successfully build and deploy the docs. A live preview generated from this branch is available here: https://manasa-manoj-nbr.github.io/toqito/index.html |
Got it, thanks for clarifying! Maybe this is a long shot, but what are the chances you could make the docs using GH-pages look like this? The theme/look there (which I would love to include here as well) is using mkdocs Thoughts, @manasa-manoj-nbr ? |
|
The RTD configuration file has been removed. Documentation links are left unchanged for now and can be updated after this PR is merged and the GitHub Pages deployment becomes the source of truth. Sorry for relying on AI assistance during parts of this work. This is my first PR to this repository, and I’ve made sure to validate and adapt the final changes manually using the project documentation and existing workflows. |
The current documentation is built entirely around Sphinx, while the look you’re referring to is based on MkDocs, so it wouldn’t be a simple theme swap. I’d be happy to explore the MkDocs-style approach further in a separate discussion or follow-up issue. Can I look into it ? @vprusso |
That would be ideal, and if you do, I'd suggest doing this in one go on this PR. Does that seem reasonable to you? Thanks for the input, @manasa-manoj-nbr ! |
| @@ -0,0 +1,112 @@ | |||
| # Getting started | |||
There was a problem hiding this comment.
there is already a contributing guide page. is there a reason to add this separately?
There was a problem hiding this comment.
I do not understand why you need to convert each page of the docs here...
Can one not use Sphinx with github pages? The entire documentation is built around Sphinx. That's a lot of work to switch to mkdocs and I do not think either me or Vincent have the capacity to review each 'converted' page.
There was a problem hiding this comment.
I do not understand why you need to convert each page of the docs here...
Can one not use Sphinx with github pages?
One uses markdown, the other RST. I think we do need to convert the pages.
There was a problem hiding this comment.
Sorry, that seems unnecessary extra work.
There was a problem hiding this comment.
How is that unnecessary? It's a requirement for using GH-pages
There was a problem hiding this comment.
I’ve been exploring the MkDocs ecosystem and found that many of the features we relied on in Sphinx have good equivalents via plugins and markdown extensions.
I’ve already enabled pymdownx.arithmatex for math rendering, and formulas are rendering correctly with MathJax
I’m primarily referencing the official MkDocs Material documentation as well as the metriq-gym setup .
If the concern is on .py example files : MkDocs doesn’t natively support executable gallery-style Python files like Sphinx Gallery. I’ve seen a few plugin-based approaches for handling this but I haven’t tried them yet. I’ll experiment with the available options and follow up with results and a recommended approach once I have something concrete.
There was a problem hiding this comment.
I’ve been exploring the MkDocs ecosystem and found that many of the features we relied on in Sphinx have good equivalents via plugins and markdown extensions.
I’ve already enabled pymdownx.arithmatex for math rendering, and formulas are rendering correctly with MathJax
Yes, I am aware there is an ability to use mathjax in md similar to rst. That is not what I am referring to. There are more things beyond executable docstring examples and live tutorials that have been enabled by the sphinx ecosystem.
I’ll experiment with the available options and follow up with results and a recommended approach once I have something concrete.
Sorry, I do not have the capacity to review these changes. Good luck.
There was a problem hiding this comment.
Thanks for the clarification.
Just to align on next steps: I currently have a working PR that deploys the existing Sphinx documentation to GitHub Pages. The idea of switching to MkDocs came up during discussion, but I want to be careful not to move forward without explicit agreement.
Before I continue further, could you please let me know what you’d prefer?
Should I stop here and keep this PR focused only on the Sphinx to GitHub Pages deployment, or
Would you like me to proceed with a full MkDocs migration?
I’m happy to follow whichever direction makes the most sense for the project, just wanted to check before investing more time. Thanks!
There was a problem hiding this comment.
I'd opt for an all-or-nothing. The point of switching to GH-pages is to use mkdocs, so I'd opt to have this done in one PR
There was a problem hiding this comment.
Ok. Then I'll continue to work on it. Thanks
…st file to .md and bibliography
|
I have completed the basic conversions(.rst to .md) and starting to look ahead at converting the remaining Sphinx-specific pieces, especially:
From what I’ve found so far, MkDocs doesn’t seem to have a direct equivalent to Sphinx Gallery (i.e., executing and rendering .py example scripts as tutorials). One possible workaround I came across is mkdocs-jupyter, which renders notebooks (or converts .py to .ipynb), but adopting this would likely require restructuring the examples and possibly how the API reference is organized. Does this sound reasonable, or is there an alternative approach or existing reference you’d suggest for handling this in the MkDocs ecosystem? @vprusso |
A quick Google search seemed to bring this up. Thoughts? |
Oh Cool. I guess this could work. I'll try and let you know |
Hi! I’ve completed most of the MkDocs migration (gallery, structure, navigation — just minor ordering left), and the API section is now linking correctly to the toqito functions. I had one clarification regarding the API reference. By this, I mean the rendered documentation that comes directly from the module docstrings (e.g., functions like pauli_channel where the full docstring — math blocks, examples, jupyter-execute, references, etc. — appears in the docs). Since these docstrings currently contain Sphinx-specific directives (.. math::, .. jupyter-execute::,), should I go ahead and fully convert them to a MkDocs-compatible format? Or would you prefer to keep them mostly as-is and ensure basic rendering works? Just wanted to confirm before modifying those sections. @vprusso 
|
Thank you @vprusso ! Working through this gave me a much deeper understanding of toqito, and I really enjoyed getting more familiar with the codebase along the way. I’m excited to contribute more to this project! |
|
Sorry, I still don't have the capacity to review this deeply. |
|
Merged. Nice work, @manasa-manoj-nbr ! |
Thank You ! |
|
Sorry, just took a quick look at the build. There are way too many DeprecationWarnings and Warning. It is very annoying to deal with errors like with this when you are working on adding a new page to the docs. Can these be fixed? Or an issue be opened for someone else to work on these? https://github.com/vprusso/toqito/actions/runs/22471380440/job/65088918422 The footcitations/citations appear to be broken as well based on the build log. 
The contributing guide is now out-of-date. Does mkdocs not allow a user to navigate between different versions of the docs? This was straightforward with RTD. The image in the readme (consequently the image for the landing page of the docs) is broken. IDK if it is an issue with this PR. Why is there an output cell for some pages in the docs and not for others? 
Is it possible for the type annotations to not show up in a single line? Maybe I am missing something here but why do the docstring examples appear before the parameter description? |
|
the citations in the docstrings could be broken too. 
|
|
There are some issues with how the references show up from bibtex. 
|
|
How does this work when I am adding a new page to the docs? Can I view the build via a PR? |
|
The examples gallery is still using |
|
cross referencing appears to be broken. 
|
This is because the first one is from examples that is rendered by mkdocs-gallery and the second one is docstrings so it is run from markdown-exec/ |
I believe I had changed everything to .md , Can you give an example where it's still using .rst |
? There are also |
Is there no way to add an output cell for the docstring examples? They just show up weirdly formatted otherwise... As stated earlier, I cannot review this deeply. Sorry. Took a quick look, made some suggestions. That is all I can do. |
I created a separate mkdocs/ folder for the new documentation setup and rendering. I didn’t delete the existing docs/ folder yet because I wanted to ensure everything works properly first. Once everything is stable and confirmed, I planned to clean that up as well. |
Thank you for the suggestions —I really appreciate it. I’ll go through them carefully and work on addressing the points you raised. |
|
I believe this MR should resolve the failures: Assuming it passes the pipeline, I'll go ahead and merge it in shortly. |
Description
This PR migrates the toqito documentation from ReadTheDocs to GitHub Pages. 1398
Changes
.github/workflows/docs.yml) to build and deploy the documentationuvenvironment and the existingdocsdependency groupgh-pagesbranch using GitHub PagesContext
This sets up a GitHub Pages documentation pipeline similar to the one used in:
https://github.com/unitaryfoundation/metriq-gym
The existing ReadTheDocs configuration is intentionally left unchanged so the new deployment can be reviewed independently before any removal decisions are made.
Notes
Documentation has been verified to build successfully in CI and renders correctly when served from GitHub Pages.
Preview: https://manasa-manoj-nbr.github.io/toqito/index.html