search

Qiskit / qiskit_sphinx_theme

A Sphinx theme and documentation guidelines for Qiskit and Qiskit Ecosystem projects
https://qisk.it/docs-guide
Apache License 2.0
15 stars 29 forks source link

[experiment] Add `remove_methods_from_toc` option to speed up docs #474

Closed Eric-Arellano closed 1 year ago

Eric-Arellano commented 1 year ago

An attempt to work around https://github.com/Qiskit/qiskit_sphinx_theme/issues/328 by pre-processing the table of contents before Furo gets to it by removing all pages that look like methods. We're limited in the logic to only being able to look at page names and can't e.g. determine level of nesting.

This is an alternative to setting the navigation_depth (https://github.com/pradyunsg/furo/pull/674 and https://github.com/Qiskit/qiskit_sphinx_theme/pull/451).

The better approach is for projects to get rid of the methods pages entirely, but this gives a workaround.

Eric-Arellano commented 1 year ago

This resulted in a Terra docs build of 1.5 hours rather than 3.5 hours. A big improvement, but still too slow.

Instead, we'll pursue two approaches:

  1. Switch Terra to not have methods pages
  2. Probably land navigation_depth option for qiskit-sphinx-theme. Even if we don't set it in prod, it will make local development faster.