Migrate projects away from qiskit.org domain #578
Comments
Qiskit documentation now lives in docs.quantum.ibm.com and has its own analytics mechanism. The Qiskit Ecosystem projects will be migrating to GitHub pages. Qiskit/ecosystem#578. Given that, I doubt we'll want to commit to still maintaining this analytics mechanism. Maintenance is more than only the code: it also means committing to helping projects access the dashboard. Instead, keep this Sphinx theme as simple as possible to make it more sustainable. Projects highly interested in analytics could always add the functionality their own way.
Instructions to set up GitHub Pages:Here, you can find a quick guide to set up your repository to use GitHub Pages. Warning Before starting with the process, you need to add a new branch called Once you have the branch
After following these steps, you will be able to deploy your website. The default URL where you can find your site is For further information, you can see the GitHub Pages Quickstart. Why do we use a publishing source (gh-pages branch)?As you have probably seen, GitHub launched a new method (currently in Beta) to deploy to GitHub Pages using GitHub actions, but we are still using a publishing source (gh-pages branch) for the deployment of the documentation. The reason behind this is the flexibility we have using a different branch to make incremental deployments. Some projects have historical API versions and need to publish to the page without modifying what is live or without having to rebuild and re-deploy everything. The deployment with GitHub actions doesn't allow us to do that because the deployment is treated as an atomic operation that has to be performed at once. Therefore, the more convenient approach is to continue deploying the documentation with a publishing source. Even though not all the projects use historical API versions, it's useful to have all the workflows ready for projects to deploy historical versions in the future and to maintain consistency between the ecosystem. You can find more information about this in the following issues that explore the possibility of having, in the future, the option to download the live site from GitHub Pages to avoid the problem of rebuilding everything: |
|
Rustworkx has been completed with: Qiskit/rustworkx#1037 and the new home of the documentation is: https://www.rustworkx.org/ |
|
@Eric-Arellano can you make https://qiskit.org/ecosystem/rustworkx/ redirect to https://www.rustworkx.org/? It will help users with the old link. Thanks! |
|
@mtreinish is way ahead of you :) He has a PR up for review to set up the redirect. Thanks @IvanIsCoding for your great work on this PR! |
|
Qiskit Algorithms docs are now on github pages https://qiskit-community.github.io/qiskit-algorithms/ thanks to @arnaucasau for the updated workflow that does this. |
## Summary This PR changes the `docs.yml` and `docs_dev.yml` workflows to deploy the documentation to GitHub Pages to migrate the project away from the qiskit.org domain. More information about the change and a quick guide to set up GitHub pages can be found at: Qiskit/ecosystem#578 Reminder task for maintainers to update the docs link in the About text for the repo on the main page once this change happens and the docs are re-deployed. This will need backporting to stable branches. - [ ] Update About text doc link ## Details The PR adds three new workflows, replacing the ones used to deploy to qiskit.org (`docs.yml` and `docs_dev.yml`). The new workflows replicate the same structure used by the old workflows when the documentation was pushed to qiskit.org using the `rclone` command. The documentation will be deployed into the `gh-pages` branch where we will find the latest release in the root of the branch. In addition, we will have one folder named `stable/` for all the previous releases and a second one for the dev docs named `dev/`. gh-pages branch structure example: ``` |- unversioned docs |- stable/ |- stable version1/ |- stable docs |- stable version2/ |- stable docs |- dev/ |- dev docs ``` The three new workflows are: **docs_release.yml** (Docs Publish): This workflow allows us to deploy the docs to GitHub pages into the root of the `gh-pages` branch. This will be the unversioned release we will find on the website. **docs_stable.yml** (Stable Docs Publish): This workflow deploys the release we choose into the `stable/` folder. The documentation will be accessible using the `Previous Releases` collapsible menu in the sidebar. **docs_dev.yml** (Dev Docs Publish): Same workflow as `docs_dev.yml` but deploying the documentation to the `dev/` folder in the `gh-pages` branch. The `docs_release.yml` and the `docs_stable.yml` workflows split the current `docs.yml` workflow into two phases. This change is useful to have more control over what versions we want to deploy. With the old workflow, we needed to deploy everything in a specific order to have the latest version as the unversioned one on the website. With the two workflows, we will be able to re-deploy stable versions when necessary. --------- Co-authored-by: Helena Zhang <Helena.Zhang@ibm.com>
## Summary This PR changes the `docs.yml` and `docs_dev.yml` workflows to deploy the documentation to GitHub Pages to migrate the project away from the qiskit.org domain. More information about the change and a quick guide to set up GitHub pages can be found at: Qiskit/ecosystem#578 Reminder task for maintainers to update the docs link in the About text for the repo on the main page once this change happens and the docs are re-deployed. This will need backporting to stable branches. - [ ] Update About text doc link ## Details The PR adds three new workflows, replacing the ones used to deploy to qiskit.org (`docs.yml` and `docs_dev.yml`). The new workflows replicate the same structure used by the old workflows when the documentation was pushed to qiskit.org using the `rclone` command. The documentation will be deployed into the `gh-pages` branch where we will find the latest release in the root of the branch. In addition, we will have one folder named `stable/` for all the previous releases and a second one for the dev docs named `dev/`. gh-pages branch structure example: ``` |- unversioned docs |- stable/ |- stable version1/ |- stable docs |- stable version2/ |- stable docs |- dev/ |- dev docs ``` The three new workflows are: **docs_release.yml** (Docs Publish): This workflow allows us to deploy the docs to GitHub pages into the root of the `gh-pages` branch. This will be the unversioned release we will find on the website. **docs_stable.yml** (Stable Docs Publish): This workflow deploys the release we choose into the `stable/` folder. The documentation will be accessible using the `Previous Releases` collapsible menu in the sidebar. **docs_dev.yml** (Dev Docs Publish): Same workflow as `docs_dev.yml` but deploying the documentation to the `dev/` folder in the `gh-pages` branch. The `docs_release.yml` and the `docs_stable.yml` workflows split the current `docs.yml` workflow into two phases. This change is useful to have more control over what versions we want to deploy. With the old workflow, we needed to deploy everything in a specific order to have the latest version as the unversioned one on the website. With the two workflows, we will be able to re-deploy stable versions when necessary. --------- Co-authored-by: Helena Zhang <Helena.Zhang@ibm.com> (cherry picked from commit b605472) # Conflicts: # docs/conf.py # tools/deploy_documentation.sh # tools/deploy_documentation_dev.sh
|
At what point are the redirects from ecosystem going to be setup. Algorithms docs have been deployed to github pages for a while but are not yet redirecting. Asking since I am about to redeploy Finance, as the first of the apps, once the backported PR to change things passes and is merged, which will all need redirects once they are live on github pages. I can note here, like I did for the algos, when its done, but like algos they will need the redirects added. |
|
Thanks to @arnaucasau Qiskit Finance docs are now published on qithub pages https://qiskit-community.github.io/qiskit-finance/ - English only at present. Do we want to populate the translations that exist before going further - i.e. changing About link and adding ecosystem redirect. Presently selecting anything other than English results in a 404 error since locales is empty for now. Qiskit Optimization is done https://qiskit-community.github.io/qiskit-optimization/
Qiskit Nature is now done too https://qiskit-community.github.io/qiskit-nature/ So that's all the app repos done now; Finance, Machine Learning, Optimization and Nature. Update: 26 Jan 2024. @arnaucasau did PRs to gh_pages adding the translations. They are merged and now live - so I altered the docs links in the repos' About to the github pages since the docs are complete - well aside from changing some cross sites links either via intersphinx, if they are auto generated, or manually fixing them up. I see in translations interphinx links, like to qiskit, are still to qiskit.org. Changing the interphinx in conf.py will only fixup the English version right when docs are redeployed from the repo. If the translations are not going to be updated maybe its ok that they continue to go via redirects. |
Arnau will be adding them this week, although it sometimes takes 1-2 days for the cloud team to review and merge.
Yeah, I think that's a good idea. The translations team finalized a few days ago the translations, so Arnau is working on setting up the translations in GitHub Pages. Those will be a one-time deploy since we are no longer actively doing the translations program for Qiskit Ecosystem. |
|
Experiments is done: https://qiskit-extensions.github.io/qiskit-experiments/ |
|
I noticed this above in the task list against Aer
This is also true (redirects from qiskit.org/documentation) for the apps as they were moved out of the main qiskit docs to ecosystem where they were before. Eg https://qiskit.org/documentation/nature which redirects to nature in ecosystem etc. |
Thanks, Steve. We got those covered, too. Arnau's PR is up for review 🙌 |
|
Can/should any branch protection rules be setup for |
|
For the apps, with the translations being added, I made the About link the github pages one. See the update in this comment #578 (comment) for more info - though that kept things about the apps in one place (in that one comment mainly) I wondered whether it might not get easily noticed hence this additional new comment pointing that out. |
|
Hi @woodsp-ibm , I think you should be able to set up a branch protection rule, and it's a good idea. The only thing to have in mind is to allow the workflow to force push to the branch as you said. I found we can allow specified actors to bypass a rule, so maybe this can help. |
|
All sites are now deployed, and we have a PR to set up redirects for the final 3 projects. Excellent job, @arnaucasau, leading this change! |
This only impacts sites hosted on qiskit.org. We need to:
tools/deploy_documentation.shandtools/rclone.conf.enc.qiskit.org/documentation/my_projectalso.Simple sites to migrate:
More complex because translations. TBD if we want to continue with this program.
More complex because Previous Releases feature:
For translations and previous releases, the challenge might be if we need to deploy the site as a single atomic unit. Right now, we deploy each subsite distinctly, like
/ecosystem/naturefor the current English docs, but/ecosystem/nature/locale/es_UNfor the Spanish docs; those deploys happen at different times. I'm concerned if GitHub pages makes us copy over the entire/naturefolder and all subfolders like translations in a single pass. But my fear might be unfounded! See Qiskit/rustworkx#1035 for some experimentation.The text was updated successfully, but these errors were encountered: