Skip to content

Commit

Permalink
Fix detection of module metadata with API generation (#221)
Browse files Browse the repository at this point in the history
In Qiskit docs, which use an older version of Sphinx, the module ID is
set with HTML like this:

```html
<span class="target" id="module-qiskit.circuit">
               <span id="qiskit-circuit"></span>
             </span>
```

But in Runtime with Sphinx 7.2, it is set like this, without the
`.target` class:

```html
<span id="module-qiskit_ibm_runtime.options"></span>
```

So, we were failing to set metadata for modules, which caused those
files to not have "front matter" (Markdown metadata) and to not show up
in the TOC. See #67.

Note that we still look at `section` to determine the module metadata,
too. There continue to be some pages in IBM Provider that set their
module metadata that way.
  • Loading branch information
Eric-Arellano authored Oct 20, 2023
1 parent c440207 commit 00d462f
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 12 deletions.
32 changes: 24 additions & 8 deletions scripts/lib/sphinx/sphinxHtmlToMarkdown.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -815,26 +815,42 @@ By default this is sys.stdout.</p></li>
`);
});

test("extract module meta for .target", async () => {
test("extract module metadata", async () => {
// Sphinx <= 7.1 uses this style.
expect(
(
await toMdWithMeta(
`<div role='main'>
<article itemprop="articleBody" id="pytorch-article" class="pytorch-article">
<span class="target" id="module-qiskit_ibm_runtime"></span>
</article>
</div>`,
`<article role='main'>
<span class="target" id="module-qiskit.circuit">
<span id="qiskit-circuit"></span>
</span>
</article>`,
)
).meta,
).toMatchInlineSnapshot(`
{
"python_api_name": "qiskit_ibm_runtime",
"python_api_name": "qiskit.circuit",
"python_api_type": "module",
}
`);
// Sphinx 7.2+ uses this style.
expect(
(
await toMdWithMeta(
`<article role='main'>
<span id="module-qiskit_ibm_runtime.options"></span>
</article>`,
)
).meta,
).toMatchInlineSnapshot(`
{
"python_api_name": "qiskit_ibm_runtime.options",
"python_api_type": "module",
}
`);
});

test("extract module meta for section", async () => {
test("extract module metadata for section", async () => {
expect(
await toMdWithMeta(`<div role="main"><section id="module-qiskit_ibm_provider.transpiler.passes.basis">
<span id="basis"></span><h1>basis<a class="headerlink" href="#module-qiskit_ibm_provider.transpiler.passes.basis" title="Permalink to this heading">¶</a></h1>
Expand Down
7 changes: 3 additions & 4 deletions scripts/lib/sphinx/sphinxHtmlToMarkdown.ts
Original file line number Diff line number Diff line change
Expand Up @@ -302,17 +302,16 @@ export async function sphinxHtmlToMarkdown(options: {
$el.replaceWith(`<pre class="math">${$el.html()}</pre>`);
});

// extract module meta
// extract module metadata
const modulePrefix = "module-";
const moduleIdWithPrefix = $main
.find(`.target, section`)
.find("span, section")
.toArray()
.map((el) => $page(el).attr("id"))
.find((id) => id?.startsWith(modulePrefix));
if (moduleIdWithPrefix) {
const moduleId = moduleIdWithPrefix.slice(modulePrefix.length);
meta.python_api_type = "module";
meta.python_api_name = moduleId;
meta.python_api_name = moduleIdWithPrefix.slice(modulePrefix.length);
}

// Update headings of modules
Expand Down

0 comments on commit 00d462f

Please sign in to comment.