## Background
First part of https://github.com/Qiskit/documentation/issues/9. The docs
infrastructure expects MDX files, but `qiskit`, `qiskit-ibm-provider`,
and `qiskit-ibm-runtime` use Sphinx to generate their API references
from source code. So, @axelhzf created a pipeline to convert Sphinx
output to MDX.
We are moving that pipeline to live in open source since the API
references are also open source.
## What this PR does
This adds the `lib/sphinx` code and its tests. The code is copied over
without change, other than adding copyright headers. The PR also sets up
Jest.
A follow up PR will add the actual parsing script. I split up the PRs
since this adds non-trivial infrastructure like Jest, so to have a
smaller PR to review.
This code will be deleted from the internal repository once
https://github.com/Qiskit/documentation/issues/9 is complete and the
internal repository is consuming this one.
## Why Jest?
We use Playwright in https://github.com/Qiskit/qiskit_sphinx_theme, so I
considered using that too here for consistency.
But I stuck with the internal repo's decision to use Jest because
Playwright doesn't have an equivalent to `toMatchInlineSnapshot`. I
think Playwright is awesome, but we're never going to have Playwright
integration tests in this repository since we're not testing the docs
site itself in this repo, i.e. we don't need to spin up a server. Jest
is simpler for our unit tests.
Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
In the closed source repository that consumes Qiskit/docs, we have this
same check for valid file metadata. It is useful to run it here too so
that we fail more eagerly.
Like the internal code, this uses TypeScript. It makes the code more
readable and better aligned with the internal code.
---------
Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
Closes https://github.com/Qiskit/docs/issues/3. We use the same open
source workflow we use with qiskit.org and qiskit-sphinx-theme.
We only preview the docs for PRs built directly on this repository, not
for forks. That is a security restriction due to how forks work.
Closes https://github.com/Qiskit/docs/issues/5.
This sets up some initial infrastructure for the repository, like CI and
the folder structure from @axelhzf's proof of concept of how to open
source documentation content.
Follow up PRs will build on this infrastructure as part of
https://github.com/Qiskit/docs/milestone/1.
## Synchronizing cSpell config with closed source
This PR copies the closed source config for cSpell.
It's a bummer that this config is duplicated. I considered if we should
automate synchronizing the config file, which would need to be the
closed source repo pulling in the closed source file, since the open
source repo cannot access the closed source repo. But I think it's not
worth the complexity to automate this, at least for now.
The closed source repository will open up a PR to use a new version of
this qiskit/docs repository. That PR will run its own spellcheck. So if
there is new content with typos, the spellcheck will fail, which is a
signal that we need to update the closed source cSpell config.
If this ends up not being sustainable, then I recommend we figure out
how to automate syncing. But for now, keep it simple.
---------
Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
Co-authored-by: Eric Harvey <eric@harvey.io>
Eric Arellano