Makes two refactors:
1. Removes creation of `apidoc/` and `stubs/` markdown folders. We never
wrote to these folders. We already create the markdown folder in
`updateApiDocs.ts` if it doesn't exist, so this wasn't necessary.
2. Removes the implicit requirement that `copyImages` is called before
`postProcessResults` so that method inlining doesn't break the images.
Now you can run `copyImages` whenever.
This is a refactor to unblock the new integration test in
https://github.com/Qiskit/documentation/issues/715. We need to test the
conversion pipeline, so its code needs to live in `lib` not `commands`.
I renamed the function `convertHtmlToMarkdown` to instead
`runConversionPipeline` and moved it to `conversionPipeline.ts`. I
didn't want the phrase "html to markdown" because because we already
have `htmlToMd.ts`; this pipeline does way more than convert HTML to
markdown, such as also copying image files and inlining methods into
classes.
This PR also refactors the rest of `updateApiDocs.ts` via helper
functions. A follow up will refactor `conversionPipeline.ts`.
Closes https://github.com/Qiskit/documentation/issues/932.
We decided:
1. We are going to keep showing h1s for class and function pages. It's
useful because they have non-trivial code at the top level, like their
docstring and constructor. It's nice to have the quick way to access the
value.
2. For now at least, we won't show h4s in the module pages. There are 8
module pages in the current API docs that use h4s. I think showing h4s
improved ~3 of them, and made ~5 worse. So, for now, let's not include
them. This can be revisited, especially after
https://github.com/Qiskit/documentation/issues/942.
This regens all APIs but reverts dev docs, which have unrelated changes
and will be regenerated in a dedicated PR.
Adding documentation of the new features and changes available after the
release of versions 0.2.0 & 0.2.1 of the `qiskit_transpiler_service`
---------
Co-authored-by: ABBY CROSS <across@us.ibm.com>
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 #845
This PR refactors the `htmlToMd.ts` script. It splits the
`prepareHandlers` function into some helper functions to simplify the
logic and improve the readability.
Part of https://github.com/Qiskit/documentation/issues/517.
Turns out that we would accidentally delete all the GitHub links for
methods because we were using `closest().remove()` rather than
`.closest().first().remove()`. That means that we'd only have the link
for the class definition and not individual methods, which defeats the
point of precise source code links from
https://github.com/Qiskit/documentation/issues/517.
## Historical API docs
However, the behavior to not show methods is actually quite sensible for
our API docs, where we were using `sphinx.ext.viewcode` rather than
`sphinx.ext.linkcode`. That meant that we could only link to the overall
file, rather than specific line numbers. So, it's not very useful to
keep linking to the overall file for every method since they will each
have the same value and the class definition already has the value. So,
we check if the link is for a method and proactively remove it if so.
This change to proactively remove method links changes some historical
API doc versions, but not others. Why? It only removes the links if we
were doing method inlining, where the method had a dedicated HTML page
originally. That's because the `.remove()` line wouldn't impat the
distinct HTML pages.
The logic that calculates the URL to display to the user expects the
page to belong to a course. This crashes when uploading a tutorial as
tutorials don't belong to a course.
This PR fixes that and updates the e2e test to include a tutorial page.
***
Resolves#799
Part of #845
This is the first refactor of `htmlToMd.ts`. It brings the following
changes:
- New function named `buildMathExpression` to build math expressions
whether they are inlined or not
- New function named `removeEmphasisSpaces` to remove the initial and
trailing spaces in an emphasis node
- The Unified plugin and the creation of the handlers for it were
separated into two functions. The unified plugin was inlined into
`generateMarkdownFile`
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Closes https://github.com/Qiskit/documentation/issues/876.
This split brings several improvements:
1. Simpler internal link checker code.
2. The external link checker now deduplicates links across all files,
which avoids repeating requests.
3. The external link checker logs its progress every 20 links.
4. It's possible to check external links without checking internal
links.
We run the external link checker in our weekly cron job over all files,
other than translations and historical Qiskit versions. That change was
added in https://github.com/Qiskit/documentation/pull/913.
Closes#224
This PR fixes an issue with the API generation script that causes
regressions in attributes. For each attribute, we show on the
documentation website, its type (if exists) and its default value (if
exists).
An example of an attribute could be `instance: str | None = None` which
has the type `str | None` and the default value `None`. This is its
representation on the website:
To find the attribute and the default value, the script searches for the
index of the colon (type separator) and the index of the equal sign
(default value separator). The problem is that those two values are
optional, and we could have, for example, a default value involving a
string containing a colon symbol that would be detected as the type
separator when it's not.
To fix this, we could only search for the type separator before the
default value. We don't have any problem with the equal sign because it
cannot be a type of attribute.
The PR has regenerated all versions of qiskit, runtime, and provider.
Adds instructions on using the flake8 plugin to detect deprecated
imports.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
When I wrote the guide my brain decided that 2 circuits and 2
observables were not possible to run with Estimator V1, but they are.
This PR fixes this oversight. Thanks @beckykd for pointing it out.
Closes#167
The script was creating a title for every `<dt>` tag inside a `<dl>`
tag. This is almost always correct given that we only have a `<dt>` tag
for each method. The problem with overload methods is that we have a
`<dt>` for each `@typing.overload` definition.
For example, the `quantumcircuit.py` file overloads the definition of
for_loop:
244940a10c/qiskit/circuit/quantumcircuit.py (L4862-L4884)
This is an example of the HTML generated
```html
<dl class="py method">
<dt class="sig sig-object py" id="qiskit.circuit.QuantumCircuit.for_loop">
<span class="sig-name descname"><span class="pre">for_loop</span>
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">for_loop</span>
<dd><p>Create a <code class="docutils literal notranslate"><span class="pre">for</span></code> loop on this circuit.</p>
```
To solve the problem this PR adds an extra condition to check whether
the `<dt>` tag has an id or not. Only the first `<dt>` tag will have an
id, so we can use this fact to create only one `<h3>` for each method.
Closes#811
Fixes the out-of-date description of the `line_length` kwarg in
`QuantumCircuit.draw()` and `qiskit.visualization.circuit_drawer()` with
a description of the `fold` argument.
Fixes a bug in https://github.com/Qiskit/documentation/pull/881. It
handled `--qiskit-release-notes` correctly, but it incorrectly would
skip `--historical-apis` for Qiskit versions before 0.45.
This also loads fewer files for the migration guides.
Part of #755
This PR changes the legacy release notes links to point to the qiskit
0.45 version folder.
### How the change was done
I created a little script to transform every link in a release note file
and re-write it in the same destination. I named it `updateLinks.ts`.
```ts
import { zxMain } from "../lib/zx";
import { globby } from "globby";
import { pathExists, getRoot } from "../lib/fs";
import { readFile, writeFile } from "fs/promises";
import transformLinks from "transform-markdown-links";
zxMain(async () => {
const allVersions = (
await globby("docs/api/qiskit/release-notes/[!index]*")
).map((releaseNotesPath) =>
releaseNotesPath.split("/").pop()!.split(".").slice(0, -1).join("."),
);
for (const releaseNotesVersion of allVersions) {
const source = `${getRoot()}/docs/api/qiskit/release-notes/${releaseNotesVersion}.md`;
if (await pathExists(source)) {
updateLinksFile('qiskit', releaseNotesVersion, source, source);
}
}
});
async function updateLinksFile(pkgName: string, versionWithoutPatch: string, source: string, dest: string) {
let markdown = await readFile(source, { encoding: "utf8" });
const regexAbsolutePath = new RegExp(
"/api/" + pkgName + "/(?!release-notes)(?![0-9])",
);
markdown = transformLinks(markdown, (link, _) =>
link.replace(regexAbsolutePath, `/api/${pkgName}/0.45/`),
);
await writeFile(dest, markdown);
}
```
To execute the script using `npm run update-legacy-links` you can modify
the `package.json` file by adding the following line in the `scripts`
section:
```ts
"update-legacy-links": "node -r esbuild-register scripts/commands/updateLinks.ts"
```
Part of https://github.com/Qiskit/documentation/issues/876 to split the
internal and external link checkers into distinct programs. To do this,
it's useful to split out internal vs. external links at parse time,
whereas before we did it inside `FileBatch`. The external link checker
won't use `FileBatch`.
This is only a refactor and doesn't change the program, other than now
using `HEAD` for external link requests rather than `GET`. We also now
use a `Set` for anchors so that checking if an anchor is included is
faster.
---------
Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
We decided as part of https://github.com/Qiskit/documentation/issues/876
that we should have distinct programs for checking internal vs external
links, since they are such distinct workflows.
This PR is a refactor to prepare for that change. The link checker
program still behaves the same as before; this is only a refactor.
The legacy release notes of qiskit were generated from qiskit 0.45 and
we need to check them loading those docs. This PR groups together all
the legacy release notes in a FileBatch to avoid loading the same docs
multiple times.
Closes https://github.com/Qiskit/documentation/issues/493. This change
makes our link checker work better because it can quickly validate the
relative links and also validate anchors, whereas external links are
much slower.
---------
Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
### Summary
Part of #755
This PR changes the logic of the API generation script to only modify
the release notes file of the version we are regenerating at that
moment. Before, the release notes files contained more than one version,
and we needed to update several files, independently of what version we
were regenerating. After https://github.com/Qiskit/qiskit/pull/11840, we
can assume that the release notes files will only contain their own
versions, and we can simply our script by removing some functions.
### New logic
The API generation script will transform every link of the release notes
files to point to its version folder instead of the top level. Once we
have the correct links, we will directly write the release notes file,
if we didn't have them before, or otherwise, we will create a new file
containing the header of the old file we had and the version sections of
the new one downloaded from Box. That way, we can make manual changes
like the table added in the release notes of qiskit 0.44 without losing
them in the next regeneration.
### Functions removed
This change allows us to remove the following two functions:
The `extractMarkdownReleaseNotesPatches` function extracted all the
versions in a release notes file and stored the markdown of each patch
to posteriorly merge them under their minor version file. Now we have
one minor version per file, so we don't need to break the release notes
into pieces anymore. The new logic treats all patch versions as a block.
The `sortReleaseNotesVersions` were used to sort the patch versions.
Given that the file will have the correct order, we don't need to worry
about it either.
Removing these two functions allows us to remove the test file, given
that they composed the entire file.
Before: `.out/python/sources/qiskit/0.40.0`
After: `.sphinx-artifacts/qiskit/0.40`
We weren't storing anything else in `.out`, so there was no need to have
those subfolders.
It also isn't necessary to put the patch version in the folder name
since we only ever have one patch per minor release.
Part of #755
This PR changes how we are checking the links of the Qiskit release
notes. The link checker will check every file in a different batch
allowing us to load all the necessary files for each release note.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
This is prework for https://github.com/Qiskit/documentation/issues/493
to relativize links to docs.quantum.ibm.com.
This refactors the code that we'll be modifying:
* Always applies the link transformation, whereas before it wasn't used
on Qiskit.
* renames `updateUrl` to `normalizeUrl`
* renames `transformLink` to `relativizeLink`
* adds tests for `relativizeLink`
Adds usernames for each file, escaping based on their notification
preferences.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Follow up to https://github.com/Qiskit/documentation/pull/848. Sphinx
used to use a different HTML structure we weren't accounting for.
After this PR, there are no more bad URLs:
```
❯ rg '_downloads' -l
scripts/lib/api/htmlToMd.test.ts
scripts/lib/links/ignores.ts
scripts/lib/api/processHtml.test.ts
```
Eric Arellano