Add script to migrate to new guides/ structure
#1294
Conversation
Eric-Arellano
changed the title
This comment was marked as outdated.
This comment was marked as outdated.
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Eric-Arellano
changed the title
guides/ structure
| @@ -0,0 +1,538 @@ | |||
| # This code is a Qiskit project. | |||
There was a problem hiding this comment.
This file can be mostly skimmed. We'll work closely with the content team to finalize the page titles and new URLs. This file is the Source Of Truth™️ for the migration.
| # ------------------------------------------------------------------------------ | ||
| # Standalone pages | ||
| # ------------------------------------------------------------------------------ |
There was a problem hiding this comment.
The comments in this section are probably worth reading. It took me a while to figure out how to handle the situation.
| Entry("Get started"), | ||
| *GET_STARTED_CHILDREN, |
There was a problem hiding this comment.
This will be revamped once we have proper label support
| class Entry: | ||
| title: str | ||
| slug: str | None = field(default=None, kw_only=True) | ||
| children: tuple[Entry, ...] = field(default_factory=lambda: (), kw_only=True) |
There was a problem hiding this comment.
FYI tuple[X, ...] is the immutable version of list[X]. We need it to be immutable to set frozen=True. I originally was using list and didn't care about immutability, but it resulted in a bug with filter_entries, so I switched to this style.
| def entries_as_markdown_list( | ||
| entries: tuple[Entry, ...], *, indent: None | str = None | ||
| ) -> str: |
There was a problem hiding this comment.
There might be a more readable way to write this than how I did it with indent. But it's working well, and this program is temporary, so it's probably fine
| @@ -0,0 +1,205 @@ | |||
| # This code is a Qiskit project. | |||
There was a problem hiding this comment.
No need to review closely this file. The content team will revamp it over time.
| @@ -0,0 +1,69 @@ | |||
| { | |||
There was a problem hiding this comment.
This page is auto-generated.
We may want the data in alternative formats for future uses like setting up redirects in closed source. We can easily re-generate the file however we want.
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>
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:
/run/my-pageto/guides/my-pageThanks 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: