We are switching from Dockerhub to Container Registry. The image is
public and you do not need to set up anything specific; you only need
normal Docker.
The preview app is slow due because the it searches through the docs
folder each time we load a page. Eric had the idea to improve the speed
by removing API docs from the image. Since the API docs are so large,
this roughly halves the time taken per page load. Writers can ask to
include API docs using the `--apis` option.
Helps with https://github.com/Qiskit/documentation/issues/1720.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
We removed the remote refresh mechanism from the previews, so port 5001
is no longer relevant.
We also can now use the Dockerhub image for both `./start` and IBM Code
Engine PR previews, so we can be consistent and stop using the IBM
Container Registry version. That simplifies our infra.
For some reason, a couple weeks ago `ctrl-c` stopped properly shutting
down the Docker container when running `./start`. So I'd have to
manually kill the container.
It now works when using `--init`:
```
❯ docker run --help | grep init
--init Run an init inside the container that forwards signals and reaps processes
```
It's confusing when `./start` diverges from `docs.quantum.ibm.com`.
We now warn every time when running `./start`:
```
❯ ./start
Warning: this may be using an outdated version of the app. Run `docker pull qiskit/documentation` to check for updates.
WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
▲ Next.js 14.0.1
- Local: http://f9e8103d2cee:3000
- Network: http://172.17.0.2:3000
✓ Ready in 1377ms
[remoteRefresh] server is listening at port 5001
```
I debated always running `docker pull qiskit/documentation`
automatically, but I think it's too slow and annoying.
Part of https://github.com/Qiskit/documentation/issues/476.
This PR sets up two GitHub actions for interfacing with Crowdin.com, the
website the translation team uses for translations.
1. Upload English sources. We do this on any change to `docs/` (except
API docs), which the translation team so that they can start making
updates sooner. For example:
<img width="346" alt="Screenshot 2023-12-20 at 5 45 05 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/0ed4cbed-45db-45bb-9150-5d90bec7a0f6">
2. Download the translations. This happens once a week, which the
translations team requested. It will open up a pull request like
https://github.com/Eric-Arellano/documentation/pull/10.
## How auth works
We only need to set GitHub Secrets for CROWDIN_PROJECT_ID and
CROWDIN_PERSONAL_TOKEN. GitHub will automatically set GITHUB_TOKEN using
[this
mechanism](https://docs.github.com/en/actions/security-guides/automatic-token-authentication).
## Translations saved at `translations/` folder
This adds a top-level `translations/` folder, rather than nesting the
translations inside the `docs/` folder. For example:
<img width="367" alt="Screenshot 2023-12-20 at 5 48 09 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/42e27fd4-5c67-4ceb-aae3-8f25315f7aae">
This top-level folder is useful because it reduces noise in the `docs/`
folder. It makes it more obvious to the team what is the original source
docs vs. what is translations and should not be modified directly in
this repository.
### How this works with the app
To get docs previews working in this repo, we teach the Docker image to
mount `translations/` as if its contents were in the folder `docs/`,
since the application expects all content to live there.
When we sync the translations from open-source to closed-source for
production, we will copy the contents of `translations/` so that it
actually lives underneath `docs/`. For example,
`translations/es/support.mdx` becomes `docs/es/support.mdx`.
## Locales
As explained in https://github.com/Qiskit/documentation/issues/7, we
generally want to use the two-letter code for languages, like `es` and
`fr`. The only exception is Chinese, where we need to distinguish
between Traditional and Simplified.
This config works with that, so long as in Crowdin.com, the project sets
up this Language Mapping under the Languages settings:
<img width="475" alt="Screenshot 2023-12-20 at 5 59 19 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/adf643d1-716a-435c-9e32-9762c6570956">
## Doesn't yet add `_languages.json`
As explained in https://github.com/Qiskit/documentation/issues/7, we
will probably want a file like `_languages.json` that teaches the docs
app what each language is, such as its name to show in the language
toggle. That schema still needs to be finalized and it can be added in a
follow up.
In https://github.com/Qiskit/documentation/pull/541, we're going to need
to add semi-complex logic to our `./start` script to dynamically
discover every subfolder we have in `translations/`, then tell Docker to
mount the folder as a volume. I'd much rather write that logic in Python
than Bash.
This PR is prework so that
https://github.com/Qiskit/documentation/pull/541 is a smaller PR. It
makes no logic changes and should be a 1:1 mapping.
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/1. Running `./start` will
open up the One Docs app at localhost:3000 using content from the local
repository.
Currently, you have to log into IBM Cloud and have the correct
permissions. We will improve this with
https://github.com/Qiskit/docs/issues/53.
---------
Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
Co-authored-by: Luciano Bello <bel@zurich.ibm.com>
Frank Harkins