-
Notifications
You must be signed in to change notification settings - Fork 91
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
Patterns: script to migrate docs to new "guides" folder #1297
Comments
This is the first step in #1297. We're going to be making last-minute changes for the docs reorg, such as finalizing URLs at the last minute. So, it's useful to have a program that can immediately regenerate the entire migration for us at any time. This program will eventually generate two commits: 1. Move files to guides/ 2. Update non-API internal links, like `/run/my-page` to `/guides/my-page` Thanks to this script being checked in to version control beforehand, we will have less code to review in the final migration PR. This program is not going to be permanent. We decided in #1299 that we will not generate the Workflow index pages longterm, only in this initial PR. Instead, we'll add a validation check. So this program is only temporary while we work on the migration. ## Follow up improvements This PR is only the initial foundation of the migration program. Remaining tasks: * Finalize the page URLs * Finalize the page organization in the left ToC and Patterns Index pages * Finalize the content for the new pages * Delete the existing pages and save the change as a Git commit. * Get CI to be green when running the migration program, such as the link checker. * #1299 * #1460 --------- Co-authored-by: javabster <abby.s.mitchell@gmail.com> Co-authored-by: Arnau Casau <arnaucasau@gmail.com>
This script is now added, and should be ready to go after #1493 and upcoming PRs to close #1460 and #1462 The final migration PR will look like this:
That PR should have no manual changes, to reduce risk of code review. What about if we need to edit existing content?The migration script cannot handle making edits to existing content. Instead, we copy over exactly whatever the original content was. So far, we've been able to safely land all the changes we need before the docs reorg, and hopefully we can keep doing that. If we cannot make certain changes to existing content beforehand, then we have two approaches we can take:
|
Part of #1297. Now when you run `scripts/patterns-reorg/main.py --delete-existing`, Git will recognize which files were renamed and preserve their Git history.
This is the first step in Qiskit#1297. We're going to be making last-minute changes for the docs reorg, such as finalizing URLs at the last minute. So, it's useful to have a program that can immediately regenerate the entire migration for us at any time. This program will eventually generate two commits: 1. Move files to guides/ 2. Update non-API internal links, like `/run/my-page` to `/guides/my-page` Thanks to this script being checked in to version control beforehand, we will have less code to review in the final migration PR. This program is not going to be permanent. We decided in Qiskit#1299 that we will not generate the Workflow index pages longterm, only in this initial PR. Instead, we'll add a validation check. So this program is only temporary while we work on the migration. ## Follow up improvements This PR is only the initial foundation of the migration program. Remaining tasks: * Finalize the page URLs * Finalize the page organization in the left ToC and Patterns Index pages * Finalize the content for the new pages * Delete the existing pages and save the change as a Git commit. * Get CI to be green when running the migration program, such as the link checker. * Qiskit#1299 * Qiskit#1460 --------- Co-authored-by: javabster <abby.s.mitchell@gmail.com> Co-authored-by: Arnau Casau <arnaucasau@gmail.com>
Part of Qiskit#1297. Now when you run `scripts/patterns-reorg/main.py --delete-existing`, Git will recognize which files were renamed and preserve their Git history.
We're flattening the docs to be under a new "guides" section, like proposal 3 of #1294. This issue tracks renaming the files and setting up the new ToC.
This change needs to be well coordinated with internal changes like changing the top nav bar and adding redirects.
Git history should be preserved.
The text was updated successfully, but these errors were encountered: