[experiment] Add remove_methods_from_toc option to speed up docs

LICENSE

@@ -247,3 +247,26 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 IN THE SOFTWARE.
+
+
+The MIT License (MIT)
+
+Copyright (c) 2018 Chris Holdgraf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -37,6 +37,19 @@ Then, set up the theme by updating `conf.py`:
 1. Set `html_theme = "qiskit"`
 2. Add `"qiskit_sphinx_theme"` to `extensions`
 
+## Slow Sphinx build? Set `remove_methods_from_toc`
+
+By default, every subpage is included in the left table of contents. This can result in incredibly slow build times, especially when you have API documentation. It can also substantially increase the size of your HTML pages, which worsens the load time for the site.
+
+You can set `remove_methods_from_toc` in `conf.py` to remove pages for methods from the table of contents:
+
+```python
+# Speed up docs build and reduce HTML page size.
+remove_methods_from_toc = True
+```
+
+However, consider instead changing your Autosummary templates to stop having a dedicated HTML page per method. While Qiskit projects have historically used that approach, it is a suboptimal user experience and also results in a substantially slower docs build.
+
 ## Enable translations
 
 First, coordinate with the Translations team at https://github.com/qiskit-community/qiskit-translations to express your interest and to coordinate setting up the infrastructure.
@@ -126,41 +139,14 @@ In qiskit-sphinx-theme 1.13, we migrated to a new Sphinx theme based on Furo, wh
 
 qiskit-sphinx-theme 1.13 continues to support the legacy Pytorch theme, but support will be removed in version 2.0.
 
-To migrate:
-
-1. In `conf.py`, ensure that `"qiskit_sphinx_theme"` is in the `extensions` list.
-2. In `conf.py`, set `html_theme = "qiskit"` rather than `"qiskit_sphinx_theme"`.
-3. In `conf.py`, remove all `html_theme_options`.
-4. In `conf.py`, remove `expandable_sidebar` from `html_context`, if set. If it was set, follow the below section [How to migrate expandable_sidebar](#how-to-migrate-expandablesidebar).
-5. Render the docs and check that everything looks how expected. If not, please open a GitHub issue or reach out on Slack for help.
-
-### How to migrate expandable_sidebar
-
-With the old theme, to have expandable folders, you had to have a dedicated `.. toctree ::` directive with a `:caption:` option, like this:
-
-```rst
-.. toctree::
-  :caption: My Folder
-  :hidden:
-
-  Page 1 <page1>
-  Page 2 <page2>
-```
-
-Instead, the new theme will render the `:caption:` as a top-level section header in the left sidebar, with top-level entries for each page. See the screenshot in the PR description of https://github.com/Qiskit/qiskit_sphinx_theme/pull/384 for an example of how the old theme renders `:caption:` and compare to [the new theme](https://github.com/Qiskit/qiskit_sphinx_theme/blob/main/tests/js/snapshots.test.js-snapshots/left-side-bar-renders-correctly-1-linux.png).
-
-Additionally, the new theme renders pages with their own subpages as expandable folders, unlike the old theme. [For example](https://github.com/Qiskit/qiskit_sphinx_theme/blob/main/tests/js/snapshots.test.js-snapshots/left-side-bar-renders-correctly-1-linux.png), `<apidocs/index>` will include all subpages that are listed in the `.. toctree ::` of the page `apidocs/index.rst`.
+To migrate, in `conf.py`:
 
-So, when migrating, you have to decide which behavior you want:
+1. Ensure that `"qiskit_sphinx_theme"` is in the `extensions` list.
+2. Set `html_theme = "qiskit"` rather than `"qiskit_sphinx_theme"`.
+3. Remove all `html_theme_options`.
+4. Decide if you want to set `remove_methods_from_toc=True` to speed up the docs build and reduce HTML page size. The new theme includes far more . Refer to [Slow Sphinx build? Set `remove_methods_from_toc`](#slow-sphinx-build-set-removemethodsfromtoc).
 
-- Use the new theme's style. No changes necessary.
-- Use the new theme's style, but get rid of the top level section header. To implement:
-  1. Consolidate the `.. toctree ::` directive with earlier ones so that they are all in the same `toctree`.
-- Keep the `:caption:` as an expandable folder, rather than a top-level section header. To implement:
-  1. Create a new directory and RST file like `my_folder/index.rst`.
-  2. Move the `.. toctree::` directive to that page.
-  3. Get rid of the `:caption:` option.
-  4. Link to the new file `my_folder/index.rst` in the parent `index.rst` by adding it to a `.. toctree ::` in the parent.
+Then, build the docs and check that everything looks how expected. If not, please open a GitHub issue or reach out on Slack for help.
 
 ## Tip: suggested site structure
 

example_docs/docs/conf.py

@@ -80,6 +80,9 @@
 
 docs_url_prefix = "ecosystem/example_docs"
 
+# See the README's section on "Slow Sphinx Build?" for why we set this.
+remove_methods_from_toc = True
+
 # When creating a new repo, follow the instructions in this repo's README.md on
 # `Enable translations`. Remove this value if you aren't using translations.
 translations_list = [

requirements-dev.txt

@@ -16,3 +16,4 @@ pytest==7.*
 
 # Types
 types-docutils
+types-Pygments

src/qiskit_sphinx_theme/__init__.py

@@ -15,7 +15,12 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from qiskit_sphinx_theme import directives, previous_releases, translations
+from qiskit_sphinx_theme import (
+    directives,
+    previous_releases,
+    translations,
+    trim_toctree,
+)
 
 if TYPE_CHECKING:
     import sphinx.addnodes
@@ -97,11 +102,13 @@ def setup(app: sphinx.application.Sphinx) -> dict[str, bool]:
 
     # We always activate these plugins, but they are only used when users:
     # * use the directives in their RST,
-    # * set `translations_list` in conf.py, or
-    # * set `versions_list` in conf.py.
+    # * set `translations_list` in conf.py,
+    # * set `versions_list` in conf.py, or
+    # * set `remove_methods_from_toc` in `conf.py`,
     directives.setup(app)
     previous_releases.setup(app)
     translations.setup(app)
+    trim_toctree.setup(app)
 
     app.add_html_theme("qiskit_sphinx_theme", _get_theme_absolute_path("pytorch"))
     app.add_html_theme("qiskit", _get_theme_absolute_path("theme/qiskit-sphinx-theme"))

src/qiskit_sphinx_theme/trim_toctree.py

@@ -0,0 +1,70 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import sphinx.addnodes
+
+if TYPE_CHECKING:
+    import sphinx.application
+    import sphinx.environment
+
+
+def setup(app: sphinx.application.Sphinx) -> None:
+    app.add_config_value("remove_methods_from_toc", default=False, rebuild="html", types=[bool])
+    app.connect("env-updated", trim_toctree)
+
+
+def is_method_stub(stub_path: str) -> bool:
+    regex = re.compile(r"stubs/.*\.[A-Z][a-zA-Z0-9]*\.[a-z_0-9]+$")
+    return bool(re.match(regex, stub_path))
+
+
+def trim_toctree(app: sphinx.application.Sphinx, env: sphinx.environment.BuildEnvironment) -> None:
+    """
+    Remove method pages from the left table of contents because they dramatically slow down docs
+    builds and bloat HTML page size.
+
+    See https://github.com/Qiskit/qiskit_sphinx_theme/issues/328 and
+    https://github.com/pradyunsg/furo/pull/674.
+
+    Note that more robust is for repositories to reorganize their code to not have dedicated pages.
+    But this provides an escape hatch while migrating.
+
+    Code inspired by sphinx-remove-toctrees (created by Chris Holdgraf) and used under the MIT
+    license.
+    """
+    if not app.config.remove_methods_from_toc:
+        return
+
+    to_remove = []
+    srcdir = Path(env.srcdir)
+    for stub in srcdir.glob("stubs/*"):
+        rel_path = str(stub.relative_to(srcdir).with_suffix(""))
+        if is_method_stub(rel_path):
+            to_remove.append(rel_path)
+
+    for _, tocs in env.tocs.items():
+        for toctree in tocs.traverse(sphinx.addnodes.toctree):
+            new_entries = []
+            for entry in toctree.attributes.get("entries", []):
+                if entry[1] not in to_remove:
+                    new_entries.append(entry)
+            # If there are no more entries, just remove the toctree.
+            if len(new_entries) == 0:
+                toctree.parent.remove(toctree)
+            else:
+                toctree.attributes["entries"] = new_entries

tests/py/trim_toctree_test.py

@@ -0,0 +1,51 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+import pytest
+
+from qiskit_sphinx_theme.trim_toctree import is_method_stub
+
+
+@pytest.mark.parametrize(
+    "stub",
+    [
+        "stubs/api_example.Electron.compute_momentum",
+        "stubs/api_example.Electron.compute231",
+        "stubs/api_example.ElectronSubclass.compute_momentum",
+        "stubs/api_example.ElectronSubclass.compute231",
+        "stubs/api_example.Electron123.compute_momentum",
+        "stubs/api_example.Electron123.compute231",
+        "stubs/api_example.submodule_123.Electron.compute_momentum",
+        "stubs/api_example.submodule_123.Electron.compute231",
+    ],
+)
+def test_is_method_stub_true(stub: str) -> None:
+    assert is_method_stub(stub) is True
+
+
+@pytest.mark.parametrize(
+    "stub",
+    [
+        "stubs/api_example.electron.compute_momentum",
+        "stubs/api_example.electron.compute231",
+        "stubs/api_example.electron.compute.momentum",
+        "stubs/api_example.electronSubclass.compute_momentum",
+        "stubs/api_example.electronSubclass.compute231",
+        "stubs/api_example.submodule_123.Electron",
+        "stubs/api_example.submodule_123.Electron123",
+        "stubs/api_example",
+        "api_example.Electron.compute_momentum",
+        "another_folder/api_example.Electron.compute_momentum",
+    ],
+)
+def test_is_method_stub_false(stub: str) -> None:
+    assert is_method_stub(stub) is False