|
10 | 10 | # copyright notice, and modified files need to carry a notice indicating |
11 | 11 | # that they have been altered from the originals. |
12 | 12 |
|
13 | | -# pylint: disable=invalid-name |
| 13 | +# pylint: disable=invalid-name,missing-function-docstring |
14 | 14 |
|
15 | 15 | """Sphinx documentation builder.""" |
16 | 16 |
|
17 | 17 | import datetime |
18 | 18 | import doctest |
19 | 19 | import os |
| 20 | +import subprocess |
20 | 21 |
|
21 | 22 | project = "Qiskit" |
22 | 23 | project_copyright = f"2017-{datetime.date.today().year}, Qiskit Development Team" |
|
27 | 28 | # The full version, including alpha/beta/rc tags |
28 | 29 | release = "0.25.0" |
29 | 30 |
|
| 31 | +# For 'qiskit_sphinx_theme' tells it we're based at 'https://qiskit.org/<docs_url_prefix>'. |
| 32 | +# Should not include the subdirectory for the stable version. |
| 33 | +docs_url_prefix = "documentation" |
| 34 | + |
| 35 | +rst_prolog = f".. |version| replace:: {version}" |
| 36 | + |
30 | 37 | extensions = [ |
31 | 38 | "sphinx.ext.napoleon", |
32 | 39 | "sphinx.ext.autodoc", |
|
58 | 65 |
|
59 | 66 | pygments_style = "colorful" |
60 | 67 |
|
| 68 | +panels_css_variables = { |
| 69 | + "tabs-color-label-active": "rgb(138, 63, 252)", |
| 70 | + "tabs-color-label-inactive": "rgb(221, 225, 230)", |
| 71 | +} |
| 72 | + |
| 73 | + |
61 | 74 | # This adds the module name to e.g. function API docs. We use the default of True because our |
62 | 75 | # module pages sometimes have functions from submodules on the page, and we want to make clear |
63 | 76 | # that you must include the submodule to import it. We should strongly consider reorganizing our |
|
70 | 83 | # (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F). |
71 | 84 | modindex_common_prefix = ["qiskit."] |
72 | 85 |
|
| 86 | +# ---------------------------------------------------------------------------------- |
| 87 | +# Extlinks |
| 88 | +# ---------------------------------------------------------------------------------- |
| 89 | +# Refer to https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html |
| 90 | +extlinks = { |
| 91 | + "pull_terra": ("https://github.com/Qiskit/qiskit-terra/pull/%s", "qiskit-terra #%s"), |
| 92 | + "pull_aer": ("https://github.com/Qiskit/qiskit-aer/pull/%s", "qiskit-aer #%s"), |
| 93 | + "pull_ibmq-provider": ( |
| 94 | + "https://github.com/Qiskit/qiskit-ibmq-provider/pull/%s", |
| 95 | + "qiskit-ibmq-provider #%s", |
| 96 | + ), |
| 97 | +} |
| 98 | + |
73 | 99 | intersphinx_mapping = { |
74 | 100 | "rustworkx": ("https://qiskit.org/ecosystem/rustworkx/", None), |
75 | 101 | "qiskit-ibm-runtime": ("https://qiskit.org/ecosystem/ibm-runtime/", None), |
|
83 | 109 | # HTML theme |
84 | 110 | # ---------------------------------------------------------------------------------- |
85 | 111 |
|
86 | | -html_theme = "qiskit_sphinx_theme" |
| 112 | +html_theme = "qiskit" |
| 113 | +html_favicon = "images/favicon.ico" |
87 | 114 | html_last_updated_fmt = "%Y/%m/%d" |
88 | | -html_theme_options = { |
89 | | - "logo_only": True, |
90 | | - "display_version": True, |
91 | | - "prev_next_buttons_location": "bottom", |
92 | | - "style_external_links": True, |
93 | | -} |
| 115 | +html_context = { |
| 116 | + "analytics_enabled": os.getenv("QISKIT_ENABLE_ANALYTICS", False) |
| 117 | +} # enable segment analytics for qiskit.org/documentation |
| 118 | +html_static_path = ["_static"] |
94 | 119 |
|
95 | 120 | # ---------------------------------------------------------------------------------- |
96 | 121 | # Autodoc |
|
107 | 132 | # return type is always added to the description (if in the signature). |
108 | 133 | autodoc_typehints_description_target = "documented_params" |
109 | 134 |
|
| 135 | +autoclass_content = "both" |
| 136 | + |
110 | 137 | autosummary_generate = True |
111 | 138 | autosummary_generate_overwrite = False |
112 | 139 |
|
|
127 | 154 | "qiskit.pulse.library.Sech": "qiskit.pulse.library.Sech_fun.rst", |
128 | 155 | } |
129 | 156 |
|
130 | | -autoclass_content = "both" |
131 | | - |
132 | 157 | # We only use Google-style docstrings, and allowing Napoleon to parse Numpy-style docstrings both |
133 | 158 | # slows down the build (a little) and can sometimes result in _regular_ section headings in |
134 | 159 | # module-level documentation being converted into surprising things. |
|
153 | 178 | # output |
154 | 179 | doctest_test_doctest_blocks = "" |
155 | 180 |
|
| 181 | + |
| 182 | +# ---------------------------------------------------------------------------------- |
| 183 | +# Plot directive |
| 184 | +# ---------------------------------------------------------------------------------- |
| 185 | + |
| 186 | +plot_html_show_formats = False |
| 187 | + |
| 188 | + |
156 | 189 | # ---------------------------------------------------------------------------------- |
157 | 190 | # Nbsphinx |
158 | 191 | # ---------------------------------------------------------------------------------- |
|
176 | 209 | __ https://github.com/Qiskit/qiskit-terra/blob/main/{{ docname }} |
177 | 210 |
|
178 | 211 | """ |
| 212 | + |
| 213 | + |
| 214 | +def add_versions_to_config(_app, config): |
| 215 | + """Add a list of old documentation versions that should have links generated to them into the |
| 216 | + context, so the theme can use them to generate a sidebar.""" |
| 217 | + # First 0.x version where Qiskit/Terra and the metapackage aligned on number. |
| 218 | + first_unified_zero_minor = 45 |
| 219 | + |
| 220 | + # Start with the hardcoded versions of the documentation that were managed while the metapackage |
| 221 | + # still existed, so are based on tags that don't exist in the Qiskit package repo. |
| 222 | + versions = ["0.19"] + [f"0.{x}" for x in range(24, first_unified_zero_minor)] |
| 223 | + |
| 224 | + proc = subprocess.run(["git", "describe", "--abbrev=0"], capture_output=True, check=True) |
| 225 | + current_version = proc.stdout.decode("utf8") |
| 226 | + current_version_info = current_version.split(".") |
| 227 | + if current_version_info[0] != "0": |
| 228 | + raise Exception("TODO: handle major versions") |
| 229 | + versions.extend( |
| 230 | + f"0.{x}" % x for x in range(first_unified_zero_minor, int(current_version_info[1]) + 1) |
| 231 | + ) |
| 232 | + config.html_context["version_list"] = versions |
| 233 | + |
| 234 | + |
| 235 | +def setup(app): |
| 236 | + app.connect("config-inited", add_versions_to_config) |
0 commit comments