From 9b5c5111b98394ddd3289037e19c3dce81dbf5aa Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Wed, 21 Aug 2024 15:34:07 -0400 Subject: [PATCH 1/2] Projects need to explicitly opt-in to Qiskit ecosystem --- README.md | 16 +++++++++++++++- example_docs/docs/conf.py | 1 + .../custom_templates/sidebar_brand.html | 3 ++- .../theme/qiskit-sphinx-theme/theme.conf | 1 + 4 files changed, 19 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..20a0fa32 100644 --- a/example_docs/docs/conf.py +++ b/example_docs/docs/conf.py @@ -27,6 +27,7 @@ "source_repository": "https://github.com/Qiskit/qiskit_sphinx_theme/", "source_branch": "main", "source_directory": "example_docs/docs/", + "sidebar_qiskit_ecosystem_member": True, } # This allows including custom CSS and HTML 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 046d714a..f2df7e73 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 = From 1f3818c876721defb73e77605b3003a3fd473888 Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Thu, 22 Aug 2024 10:02:13 -0400 Subject: [PATCH 2/2] Make config less likely to be copied --- example_docs/docs/conf.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/example_docs/docs/conf.py b/example_docs/docs/conf.py index 20a0fa32..2e9ce1ba 100644 --- a/example_docs/docs/conf.py +++ b/example_docs/docs/conf.py @@ -27,9 +27,15 @@ "source_repository": "https://github.com/Qiskit/qiskit_sphinx_theme/", "source_branch": "main", "source_directory": "example_docs/docs/", - "sidebar_qiskit_ecosystem_member": True, } +# 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"]