-
Notifications
You must be signed in to change notification settings - Fork 749
Epic - Copy documents from qiskit/qiskit-metapackage
to qiskit/qiskit-terra
#1722
Comments
Just noticed that |
Good spotted Jim! Qiskit/qiskit#10111 |
Update on this. We can't finish this until a released version of Terra has the documentation pages like But in the meantime, we can de-duplicate two folders: #1748. And that PR makes the generic infrastructure changes so that it will be easy to finish the migration once unblocked. |
<!--⚠️ If you do not respect this template, your pull request will be closed.⚠️ Your pull request title should be short detailed and understandable for all.⚠️ Also, please add it in the CHANGELOG file under Unreleased section.⚠️ If your pull request fixes an open issue, please link to the issue. ✅ I have added the tests to cover my changes. ✅ I have updated the documentation accordingly. ✅ I have read the CONTRIBUTING document. --> This makes progress towards #1722. We are not ready to yet move actual docs pages like `maintainers_guide.rst` to Terra because it requires that those docs are in a released version of Terra, such as 0.24.1. But, Terra has already had duplicate copies of `_templates` and `source_images`. So, it's safe for us to de-duplicate those folders. This PR is prework for future de-duplication. -- To simplify this PR, I removed the `DOCS_FROM_MASTER` feature, which was not used in CI or anywhere. I also tweaked the functionality of docs currently existing. We now will delete them at the end of the run. And we don't clone tutorials if they already existed.
I'm not really clear why this issue seems to be under the assumption that these documents will actually be deleted from the metapackage and not just copied to Terra/wherever? There's no need to delete them - they can just be archived as-is - and deleting them is what's causing all this worry about sequencing. These documents are very rarely touched (except |
The overriding point being that we don't need to transition how the metapackage builds its documents to Terra, we just need to make sure that all of the relevant documents are included in Terra's existing documentation build. We don't need to add extra work by having an intermediate period where the metapackage is copying more files over from Terra that it doesn't already copy - we can have the metapackage build process proceed in exactly the same way it does right up until we simply delete the On the Terra side, we can copy all the files over and make sure the docs build artifact as built by Terra's CI is what we want it to be without deleting anything from here. Once we're satisfied that it all looks right, we add a "deploy docs" action to Terra. That doesn't need to be tied to any release, and Terra doesn't even need to make a release with that system before the metapackage is archived (although of course it'd be better to test it). The only sequencing that needs to happen with that is just to ensure that the triggers for the metapackage "deploy docs" and Terra's proposed "deploy docs" are set to not conflict with each other during any period where both repos have an action. |
This sounds okay to me. Thanks @jakelishman for taking the time to write that up! Luciano and I agree your proposal is okay with us. We will keep the files in metapackage and copy them at the very end of the migration, without deleting them from this repo. |
Sounds good, thanks! I think this issue is still in need of doing, right, it's just that it's a "copy", not a "move"? I'm hopeful that it'll mean less stress for all of us, since there won't be sequencing concerns to work out. |
qiskit/qiskit-metapackage
to qiskit/qiskit-terra
qiskit/qiskit-metapackage
to qiskit/qiskit-terra
Good point. I updated the issue title and description. I'll shift my focus to what we do with qiskit-tutorials: #1724. |
…apackage#1748) This makes progress towards Qiskit/qiskit-metapackage#1722. We are not ready to yet move actual docs pages like `maintainers_guide.rst` to Terra because it requires that those docs are in a released version of Terra, such as 0.24.1. But, Terra has already had duplicate copies of `_templates` and `source_images`. So, it's safe for us to de-duplicate those folders. This PR is prework for future de-duplication. -- To simplify this PR, I removed the `DOCS_FROM_MASTER` feature, which was not used in CI or anywhere. I also tweaked the functionality of docs currently existing. We now will delete them at the end of the run. And we don't clone tutorials if they already existed.
### Summary This cross-repository merge unifies the documentation, benchmarks and code of conduct from the metapackage into Qiskit/Terra's build. There are very non-trivial merge conflicts that have been resolved by this commit. The summary is: - `CODE_OF_CONDUCT.md`: taken directly from the metapackage's version. - `docs/conf.py`: strongly unified, albeit without the translations components that are added in a separate commit. - `docs/index.rst`: taken almost verbatim from the metapackage. All the API documentation RST files on Terra are moved to `docs/apidoc` (without the trailing 's') to match the metapackage expectation, so the URLs of built documentation will not change. - `docs/release_notes.rst`: The metapackage's version is renamed to `docs/legacy_release_notes.rst`, given a small introductory header, and made an orphan linked only from a _new_ `docs/release_notes.rst` that uses `reno`. - `docs/tutorials.rst`: Mostly these were the same already. Updated to include Qiskit/Terra's correction that it's not an orphan, and contain the metapackage's extra intro tutorial. - `docs/apidoc/terra.rst`: renamed to `docs/apidoc/index.rst` and retitled to be correctly just "API Documentation". - `requirements-dev.txt`: the version of the Sphinx theme is bumped to 1.14 to match the metapackage expectation. Following merge commit ec5c9ca, there is a commit 66a5d9f that fixes the ASV build for use in Terra, which is the rollup of the post-merge commits of #10546, which this PR supersedes. ### Details and comments This should probably be merged ASAP before `main` moves on. Resolutions on the metapackage: - Fix Qiskit/qiskit-metapackage#1723 - Fix Qiskit/qiskit-metapackage#1722 - Fix Qiskit/qiskit-metapackage#1746 After this has merged, #10610 should merge which will close the remaining migration-related issues from the metapackage. The metapackage was prepared for the migration using [`git-filter-repo`](https://github.com/newren/git-filter-repo), with the scripts and configuration files contained within [metapackage_migration.zip](https://github.com/Qiskit/qiskit-terra/files/12324298/metapackage_migration.zip). If you extract that zip, you need to activate a Python 3.11 `venv` then run `metapackage_rewrite.bash` which will prepare the repo in the exact state I merged to create this PR. *edit*: In retrospect writing this, you might need to modify my script so that it pulls only starting from commit Qiskit/qiskit-metapackage@f131daf, which was the tip of `master` at the time I ran this. I tested the docs build locally and it looks as correct as I can tell. There's still big cards pointing to experiments, dynamics etc on the landing page, but I figured that enough's enough, and we can just fix those last two things in Terra. This PR does not include Qiskit/qiskit-metapackage#1791, which should be now cherry-picked onto Terra.
This cross-repository merge unifies the documentation, benchmarks and code of conduct from the metapackage into Qiskit/Terra's build. There are very non-trivial merge conflicts that have been resolved by this commit. The summary is: - `CODE_OF_CONDUCT.md`: taken directly from the metapackage's version. - `docs/conf.py`: strongly unified, albeit without the translations components that are added in a separate commit. - `docs/index.rst`: taken almost verbatim from the metapackage. All the API documentation RST files on Terra are moved to `docs/apidoc` (without the trailing 's') to match the metapackage expectation, so the URLs of built documentation will not change. - `docs/release_notes.rst`: The metapackage's version is renamed to `docs/legacy_release_notes.rst`, given a small introductory header, and made an orphan linked only from a _new_ `docs/release_notes.rst` that uses `reno`. - `docs/tutorials.rst`: Mostly these were the same already. Updated to include Qiskit/Terra's correction that it's not an orphan, and contain the metapackage's extra intro tutorial. - `docs/apidoc/terra.rst`: renamed to `docs/apidoc/index.rst` and retitled to be correctly just "API Documentation". - `requirements-dev.txt`: the version of the Sphinx theme is bumped to 1.14 to match the metapackage expectation. Following merge commit ec5c9ca, there is a commit 66a5d9f that fixes the ASV build for use in Terra, which is the rollup of the post-merge commits of Qiskit#10546, which this PR supersedes. This should probably be merged ASAP before `main` moves on. Resolutions on the metapackage: - Fix Qiskit/qiskit-metapackage#1723 - Fix Qiskit/qiskit-metapackage#1722 - Fix Qiskit/qiskit-metapackage#1746 After this has merged, Qiskit#10610 should merge which will close the remaining migration-related issues from the metapackage. The metapackage was prepared for the migration using [`git-filter-repo`](https://github.com/newren/git-filter-repo), with the scripts and configuration files contained within [metapackage_migration.zip](https://github.com/Qiskit/qiskit-terra/files/12324298/metapackage_migration.zip). If you extract that zip, you need to activate a Python 3.11 `venv` then run `metapackage_rewrite.bash` which will prepare the repo in the exact state I merged to create this PR. *edit*: In retrospect writing this, you might need to modify my script so that it pulls only starting from commit Qiskit/qiskit-metapackage@f131daf, which was the tip of `master` at the time I ran this. I tested the docs build locally and it looks as correct as I can tell. There's still big cards pointing to experiments, dynamics etc on the landing page, but I figured that enough's enough, and we can just fix those last two things in Terra. This PR does not include Qiskit/qiskit-metapackage#1791, which should be now cherry-picked onto Terra. (cherry picked from commit 965fd23)
This cross-repository merge unifies the documentation, benchmarks and code of conduct from the metapackage into Qiskit/Terra's build. There are very non-trivial merge conflicts that have been resolved by this commit. The summary is: - `CODE_OF_CONDUCT.md`: taken directly from the metapackage's version. - `docs/conf.py`: strongly unified, albeit without the translations components that are added in a separate commit. - `docs/index.rst`: taken almost verbatim from the metapackage. All the API documentation RST files on Terra are moved to `docs/apidoc` (without the trailing 's') to match the metapackage expectation, so the URLs of built documentation will not change. - `docs/release_notes.rst`: The metapackage's version is renamed to `docs/legacy_release_notes.rst`, given a small introductory header, and made an orphan linked only from a _new_ `docs/release_notes.rst` that uses `reno`. - `docs/tutorials.rst`: Mostly these were the same already. Updated to include Qiskit/Terra's correction that it's not an orphan, and contain the metapackage's extra intro tutorial. - `docs/apidoc/terra.rst`: renamed to `docs/apidoc/index.rst` and retitled to be correctly just "API Documentation". - `requirements-dev.txt`: the version of the Sphinx theme is bumped to 1.14 to match the metapackage expectation. Following merge commit ec5c9ca, there is a commit 66a5d9f that fixes the ASV build for use in Terra, which is the rollup of the post-merge commits of #10546, which this PR supersedes. This should probably be merged ASAP before `main` moves on. Resolutions on the metapackage: - Fix Qiskit/qiskit-metapackage#1723 - Fix Qiskit/qiskit-metapackage#1722 - Fix Qiskit/qiskit-metapackage#1746 After this has merged, #10610 should merge which will close the remaining migration-related issues from the metapackage. The metapackage was prepared for the migration using [`git-filter-repo`](https://github.com/newren/git-filter-repo), with the scripts and configuration files contained within [metapackage_migration.zip](https://github.com/Qiskit/qiskit-terra/files/12324298/metapackage_migration.zip). If you extract that zip, you need to activate a Python 3.11 `venv` then run `metapackage_rewrite.bash` which will prepare the repo in the exact state I merged to create this PR. *edit*: In retrospect writing this, you might need to modify my script so that it pulls only starting from commit Qiskit/qiskit-metapackage@f131daf, which was the tip of `master` at the time I ran this. I tested the docs build locally and it looks as correct as I can tell. There's still big cards pointing to experiments, dynamics etc on the landing page, but I figured that enough's enough, and we can just fix those last two things in Terra. This PR does not include Qiskit/qiskit-metapackage#1791, which should be now cherry-picked onto Terra. (cherry picked from commit 965fd23)
…10611) ### Summary This cross-repository merge unifies the documentation, benchmarks and code of conduct from the metapackage into Qiskit/Terra's build. There are very non-trivial merge conflicts that have been resolved by this commit. The summary is: - `CODE_OF_CONDUCT.md`: taken directly from the metapackage's version. - `docs/conf.py`: strongly unified, albeit without the translations components that are added in a separate commit. - `docs/index.rst`: taken almost verbatim from the metapackage. All the API documentation RST files on Terra are moved to `docs/apidoc` (without the trailing 's') to match the metapackage expectation, so the URLs of built documentation will not change. - `docs/release_notes.rst`: The metapackage's version is renamed to `docs/legacy_release_notes.rst`, given a small introductory header, and made an orphan linked only from a _new_ `docs/release_notes.rst` that uses `reno`. - `docs/tutorials.rst`: Mostly these were the same already. Updated to include Qiskit/Terra's correction that it's not an orphan, and contain the metapackage's extra intro tutorial. - `docs/apidoc/terra.rst`: renamed to `docs/apidoc/index.rst` and retitled to be correctly just "API Documentation". - `requirements-dev.txt`: the version of the Sphinx theme is bumped to 1.14 to match the metapackage expectation. Following merge commit 22a406c, there is a commit 66a5d9fe0 that fixes the ASV build for use in Terra, which is the rollup of the post-merge commits of Qiskit/qiskit#10546, which this PR supersedes. ### Details and comments This should probably be merged ASAP before `main` moves on. Resolutions on the metapackage: - Fix Qiskit/qiskit-metapackage#1723 - Fix Qiskit/qiskit-metapackage#1722 - Fix Qiskit/qiskit-metapackage#1746 After this has merged, Qiskit/qiskit#10610 should merge which will close the remaining migration-related issues from the metapackage. The metapackage was prepared for the migration using [`git-filter-repo`](https://github.com/newren/git-filter-repo), with the scripts and configuration files contained within [metapackage_migration.zip](https://github.com/Qiskit/qiskit-terra/files/12324298/metapackage_migration.zip). If you extract that zip, you need to activate a Python 3.11 `venv` then run `metapackage_rewrite.bash` which will prepare the repo in the exact state I merged to create this PR. *edit*: In retrospect writing this, you might need to modify my script so that it pulls only starting from commit Qiskit/qiskit-metapackage@f131daf, which was the tip of `master` at the time I ran this. I tested the docs build locally and it looks as correct as I can tell. There's still big cards pointing to experiments, dynamics etc on the landing page, but I figured that enough's enough, and we can just fix those last two things in Terra. This PR does not include Qiskit/qiskit-metapackage#1791, which should be now cherry-picked onto Terra.
Following RFC 0011 (epic):
All the "general documents" in needs to be moved to the qiskit/qiskit-terra to be part of a single sphinx build process.
We will move the docs build process from the metapackage to Terra.
To avoid Terra's docs infrastructure from becoming more complex, we will likely want to solve #1724 first so that we do not need to Git clone the tutorials repo.
The text was updated successfully, but these errors were encountered: