From 2e94899884a6e464fca7904dc429d69000e5f957 Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Thu, 22 Aug 2024 10:08:10 -0400 Subject: [PATCH] Projects need to explicitly opt-in to Qiskit ecosystem (#622) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We realized it's incorrect to be saying that every project that uses this theme is a part of the Qiskit ecosystem. Any project can use this theme, even projects that have nothing to do with quantum computing. However, we do still want to include the link to the ecosystem for relevant projects because it's a) good branding for the partners and b) drives traffic to the ecosystem. We decided you should opt-in to the sidebar option, rather than opt-out. We'd rather have false negatives than false positives (showing the URL when it shouldn't be). Default: Screenshot 2024-08-21 at 3 34 48 PM With option set: Screenshot 2024-08-21 at 3 35 11 PM --- README.md | 16 +++++++++++++++- example_docs/docs/conf.py | 7 +++++++ .../custom_templates/sidebar_brand.html | 3 ++- .../theme/qiskit-sphinx-theme/theme.conf | 1 + 4 files changed, 25 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e4dcf075..8c2eb383 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,7 @@ The `qiskit_sphinx_theme` extension defines the below custom directives for you You can add a custom logo by adding a logo file (SVG or PNG) as a sibling to your `conf.py`, e.g. `docs/logo.svg`. Then, set `html_logo` in `conf.py` to the name of the file, e.g. `html_logo = "logo.png"`. -When using a custom logo, you may want to disable the project's name in the sidebar by setting `sidebar_hide_name` in `html_theme_options`: +When using a custom logo, you may want to disable the project's name in the sidebar by setting `sidebar_hide_name` in `html_theme_options` in `conf.py`: ```python html_theme_options = { @@ -130,6 +130,20 @@ html_theme_options = { } ``` +## Qiskit ecosystem members + +If your project is a member of the [Qiskit ecosystem](https://www.ibm.com/quantum/ecosystem), we encourage you to set the following configuration so that the left sidebar mentions your project being in the ecosystem. + +Update `conf.py`: + +```python +html_theme_options = { + "sidebar_qiskit_ecosystem_member": True, +} +``` + +Non-ecosystem members should not set this option. + ## Tip: suggested site structure To keep UX/UI similar across different Qiskit ecosystem packages, consider using the following structure for your sidebar, which can be set in the toctree of your `index.rst`: diff --git a/example_docs/docs/conf.py b/example_docs/docs/conf.py index c72dfd16..2e9ce1ba 100644 --- a/example_docs/docs/conf.py +++ b/example_docs/docs/conf.py @@ -29,6 +29,13 @@ "source_directory": "example_docs/docs/", } +# Members of the Qiskit ecosystem should set `sidebar_qiskit_ecosystem_member` +# explicitly in `html_theme_options`. This convoluted code is only set up +# this way to discourage projects who copy this config file from +# unintentionally configuring this option. +if project == "Example Docs": + html_theme_options["sidebar_qiskit_ecosystem_member"] = True + # This allows including custom CSS and HTML templates. html_static_path = ["_static"] templates_path = ["_templates"] diff --git a/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_brand.html b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_brand.html index 00cedd9d..ef9afdb1 100644 --- a/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_brand.html +++ b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_brand.html @@ -21,7 +21,8 @@ {%- endif %} {% endblock brand_content %} -{#- Add a link to the Qiskit ecosystem web page. -#} +{% if theme_sidebar_qiskit_ecosystem_member %}

This project is part of the Qiskit ecosystem

+{%- endif %} diff --git a/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/theme.conf b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/theme.conf index faf45327..d20fa8ff 100644 --- a/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/theme.conf +++ b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/theme.conf @@ -24,5 +24,6 @@ sidebars = custom_templates/sidebar_languages.html [options] +sidebar_qiskit_ecosystem_member = # This option is no longer used in v2+, but it's kept for backwards compatibility. disable_ecosystem_logo =