Projects need to explicitly opt-in to Qiskit ecosystem (#622)

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:

<img width="289" alt="Screenshot 2024-08-21 at 3 34 48 PM"
src="https://github.com/user-attachments/assets/fa952dde-054e-40ae-857a-ad653ab06ac8">

With option set:

<img width="289" alt="Screenshot 2024-08-21 at 3 35 11 PM"
src="https://github.com/user-attachments/assets/30d5e6d4-0d55-48c1-81ba-4eaadc82ff33">

README.md

@@ -122,14 +122,28 @@ 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 = {
     "sidebar_hide_name": True,
 }
 ```
 
+## 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`:

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"]

src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_brand.html

@@ -21,7 +21,8 @@
   {%- endif %}
   {% endblock brand_content %}
 </a>
-{#- Add a link to the Qiskit ecosystem web page. -#}
+{% if theme_sidebar_qiskit_ecosystem_member %}
 <p class="sidebar-ecosystem-link">
   This project is part of the <a class="reference external" href="https://www.ibm.com/quantum/ecosystem">Qiskit ecosystem</a>
 </p>
+{%- endif %}

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 =