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

Patterns: script to migrate docs to new "guides" folder #1297

Closed
Tracked by #524
Eric-Arellano opened this issue May 3, 2024 · 1 comment
Closed
Tracked by #524

Patterns: script to migrate docs to new "guides" folder #1297

Eric-Arellano opened this issue May 3, 2024 · 1 comment
Assignees

Comments

@Eric-Arellano
Copy link
Collaborator

Eric-Arellano commented May 3, 2024

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.

github-merge-queue bot pushed a commit that referenced this issue May 30, 2024
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>
@javabster javabster moved this to In Progress in Docs Planning Jun 3, 2024
@Eric-Arellano Eric-Arellano changed the title Patterns: migrate docs to new "guides" folder Patterns: script to migrate docs to new "guides" folder Jun 4, 2024
@Eric-Arellano
Copy link
Collaborator Author

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:

  1. scripts/patterns-reorg/update_internal_links.py
  2. git commit
  3. scripts/patterns-reorg/main.py --delete-existing
  4. git commit

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:

  1. Make the manual changes in the final PR
  2. Add a new mechanism to the migration script. We need to still preserve Git history, so this would probably look like still copying over the original file, then somehow updating the content after, like applying a Git diff. The content update should probably be done in a dedicated program so that it can be a dedicated Git commit.

@github-project-automation github-project-automation bot moved this from In Progress to Done in Docs Planning Jun 4, 2024
github-merge-queue bot pushed a commit that referenced this issue Jun 4, 2024
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.
frankharkins pushed a commit to frankharkins/documentation that referenced this issue Jul 22, 2024
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>
frankharkins pushed a commit to frankharkins/documentation that referenced this issue Jul 22, 2024
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.
@javabster javabster removed this from Docs Planning Feb 5, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants