Fix Furo styling for API pages with methods on class page (Cherry-pic…

…k of #458) (#478)

We're planning to switch some Qiskit projects to stop having dedicated
HTML pages per method, mostly due to performance concerns.

Closes #466. Methods
were using `inline-block` rather than `block` when on the classes page,
which resulted in a bug when highlighting over the method to show the
`#` anchor tag:

![Screenshot 2023-07-07 at 11 25 45

AM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/004da4c0-3702-4cd7-9601-5baa46a992a7)

Instead, we now turn off floating of the `[source]` label because it
causes issues on long code signatures:

![Screenshot 2023-07-07 at 3 02 44

PM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/19c45f5a-8fc7-44f5-a9d8-997b9a0bfa6e)

After:

![Screenshot 2023-07-07 at 3 03 08

PM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/55e865c9-b376-40e0-846d-cfdd4b1efd1a)

Even though the `[source]` floating to the right is more "elegant", we
have too many long signatures in Qiskit to be worth it. It's safer to
turn off the float.

This also improves the information hierarchy so that page feels less
crowded. Relates to
#459:

* Use a border-width of 2px for top-level code objects, but otherwise 1
* Increases the font sizes so headings look bigger.

example_docs/docs/_templates/autosummary/class.rst

@@ -1,6 +1,5 @@
 {#
-   The general principle of this is that we manually document attributes here in
-   the same file, but give all methods their own page.  By default, we document
+   We show all the class's methods and attributes on the same page. By default, we document
    all methods, including those defined by parent classes.
 -#}
 
@@ -9,33 +8,24 @@
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
-{#-
-   Avoid having autodoc populate the class with the members we're about to
-   summarize to avoid duplication.
-#}
    :no-members:
    :show-inheritance:
-{#
-   Methods all get their own separate page, with their names and the first lines
-   of their docstrings tabulated.  The documentation from `__init__` is
-   automatically included in the standard class documentation, so we don't want
-   to repeat it.
--#}
-{% block methods_summary %}{% set wanted_methods = (methods | reject('==', '__init__') | list) %}{% if wanted_methods %}
-   .. rubric:: Methods
 
-   .. autosummary::
-      :nosignatures:
-      :toctree: ../stubs/
-{% for item in wanted_methods %}
-      ~{{ name }}.{{ item }}
-{%- endfor %}
-{% endif %}{% endblock %}
-
-{% block attributes_summary %}{% if attributes %}
+{% block attributes_summary %}
+  {% if attributes %}
    .. rubric:: Attributes
-{# Attributes should all be summarized directly on the same page. -#}
-{% for item in attributes %}
+    {% for item in attributes %}
    .. autoattribute:: {{ item }}
-{%- endfor %}
-{% endif %}{% endblock -%}
+    {%- endfor %}
+  {% endif %}
+{% endblock -%}
+
+{% block methods_summary %}
+  {% set wanted_methods = (methods | reject('==', '__init__') | list) %}
+  {% if wanted_methods %}
+   .. rubric:: Methods
+    {% for item in wanted_methods %}
+   .. automethod:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock %}

example_docs/docs/_templates/autosummary/class_no_inherited_members.rst

@@ -1,38 +1,28 @@
-{#
-   This is very similar to the default class template, except this one is used
-   when we don't want to generate any inherited methods.
--#}
+{# This is identical to class.rst, except for the filtering in `set wanted_methods`. -#}
 
 {{ objname | escape | underline }}
 
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
-{#-
-   Avoid having autodoc populate the class with the members we're about to
-   summarize to avoid duplication.
-#}
    :no-members:
    :show-inheritance:
-{#
-   Methods all get their own separate page, with their names and the first lines
-   of their docstrings tabulated.
--#}
-{% block methods_summary %}{% set wanted_methods = (methods | reject('in', inherited_members) | reject('==', '__init__') | list) %}{% if wanted_methods %}
-   .. rubric:: Methods Defined Here
 
-   .. autosummary::
-      :nosignatures:
-      :toctree: ../stubs/
-{% for item in wanted_methods %}
-      ~{{ name }}.{{ item }}
-{%- endfor %}
-{% endif %}{% endblock %}
-
-{% block attributes_summary %}{% if attributes %}
+{% block attributes_summary %}
+  {% if attributes %}
    .. rubric:: Attributes
-{# Attributes should all be summarized directly on the same page. -#}
-{% for item in attributes %}
+    {% for item in attributes %}
    .. autoattribute:: {{ item }}
-{%- endfor %}
-{% endif %}{% endblock -%}
+    {%- endfor %}
+  {% endif %}
+{% endblock -%}
+
+{% block methods_summary %}
+  {% set wanted_methods = (methods | reject('in', inherited_members) | reject('==', '__init__') | list) %}
+  {% if wanted_methods %}
+   .. rubric:: Methods
+    {% for item in wanted_methods %}
+   .. automethod:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock %}

src/qiskit_sphinx_theme/assets/styles/_api.scss

@@ -11,10 +11,12 @@
  * that they have been altered from the originals.
  */
 
-// By default, Furo uses an aggressive red color for API docs. We use a more muted black and gray.
 body {
+  // By default, Furo uses an aggressive red color for API docs. We use a more muted black and gray.
   --color-api-name: var(--color-foreground-primary);
   --color-api-pre-name: var(--color-foreground-secondary);
+  // Use normal font sizes rather than the default of `--font-size-small`.
+  --api-font-size: var(--font-size-normal);
 }
 
 // Definition lists are used for sections like "Parameters", "Return type", and "Attributes"
@@ -23,20 +25,36 @@ dl.py:not(.docutils) dt {
   // This causes the definition-term and its border-top to only take up as much space as the
   // content, plus padding and margins.
   display: inline-block;
-  border-top: 2px solid var(--qiskit-color-purple);
+  border-top: 1px solid var(--qiskit-color-purple);
   background-color: var(--color-background-secondary);
 }
 
-// Rules that impact the top-level entry for the code object, which e.g. has the `[source]` button.
+// Some code objects have a `[source]` text that normally floats to the right. While that usually
+// looks better, it results in messed up styling on long code signatures where the `[source]
+// overlaps with actual code. That often happens with Qiskit APIs, so it's not worth the sometimes
+// nicer styling.
+.viewcode-back,
+.viewcode-link {
+  float: unset;
+  text-align: unset;
+  margin-left: 0.75em;
+}
+
+// Use a thicker border for top-level code objects to distinguish from their metadata like
+// `Returns` and `Return type`.
+dl.py:not(.docutils).class > dt,
+dl.py:not(.docutils).method > dt,
+dl.py:not(.docutils).function > dt,
+dl.py:not(.docutils).attribute > dt {
+  border-top-width: 2px;
+}
+
+// Rules that impact the top-level entry for the code object at the top of the file. These add
+// spacing between the page header and the top entry. We also make it stretch across the entire
+// screen for better information hierarchy.
 section > dl.py:not(.docutils) {
   > dt {
-    // We normally want to use inline-block for definition terms so that the purple border we add on
-    // top does not stretch across the whole screen. But, we make an exception here it will have a
-    // `[source]` button that floats to the right. The spacing of that is non-trivial and was the
-    // source of issues in Pytorch, so we stick with Furo's spacing.
     display: block;
-    // Make the border less thick so its clear the top-level page header corresponds to this line.
-    border-top-width: 1px;
     margin-bottom: 1rem;
   }
 
@@ -76,7 +94,7 @@ dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.
 // section headers like "Attributes" and "Methods". We disagree with the design in
 // https://github.com/pradyunsg/furo/discussions/505. Instead, use the rules from `p.rubric`.
 dl.py dd p.rubric {
-  font-size: 1.125em;
+  font-size: 125%;  // We make this bigger than p.rubric to match the bigger font sizes for the page.
   font-weight: 700;
   line-height: 1.25;
   text-transform: unset;

tests/js/snapshots.test.js

@@ -227,17 +227,6 @@ test.describe("api docs", () => {
     await expect(content).toHaveScreenshot();
   });
 
-  test("method page", async ({ page }) => {
-    await page.goto("stubs/api_example.Electron.compute_momentum.html");
-    const content = page.locator("div.article-container");
-    await expect(content).toHaveScreenshot();
-
-    // Also test a method with @typing.overload.
-    await page.goto("stubs/api_example.Electron.overloaded_func.html");
-    const content2 = page.locator("div.article-container");
-    await expect(content2).toHaveScreenshot();
-  });
-
   test("function page", async ({ page }) => {
     await page.goto("stubs/api_example.my_function.html");
     const content = page.locator("div.article-container");