Epic - Copy documents from qiskit/qiskit-metapackage to qiskit/qiskit-terra

[1ucian0]

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.

[garrison]

Just noticed that CITATION.bib needs to move as well. Otherwise, the link from the Terra README will be broken after qiskit-terra -> qiskit.

[1ucian0]

Good spotted Jim! Qiskit/qiskit#10111

[Eric-Arellano]

Update on this. We can't finish this until a released version of Terra has the documentation pages like maintainers_guide.rst. So we're somewhat blocked.

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.

[jakelishman]

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 release_notes.rst which isn't proposed to move yet), so it seems unlikely that it would be much overhead if we do need to duplicate a PR or two during the migration window. Leaving them here removes all the sequencing worries (and I'd argue is more in the spirit of archiving a repo anyway).

[jakelishman]

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 deploy_docs.yml GitHub Action.

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.

[Eric-Arellano]

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.

[jakelishman]

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.

[Eric-Arellano]

Good point. I updated the issue title and description.

I'll shift my focus to what we do with qiskit-tutorials: #1724.