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 %} +{%- 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 =