Add the qiskit-ecosystem theme (#506)

This makes the `_qiskit-ecosystem` now public.

It also documents how to use it - closes
#486. Note that the
default theme should be `qiskit-ecosystem`; only Terra should use
`qiskit`.

Also fixes some broken links in the README - closes
#488.

CONTRIBUTING.md

@@ -18,16 +18,17 @@ There are a few important subfolders to be aware of:
 ### `/src`
 This subfolder contains the HTML, CSS, and Python files that are used for the Qiskit themes. It has these folders:
 
-* `assets`: CSS and JavaScript for our Furo theme, which is the future of the Sphinx theme.
-* `pytorch`: all the code for the legacy Pytorch theme.
-* `theme`: static files, like HTML templates, for our Furo theme.
+* `assets`: CSS and JavaScript for the `qiskit` theme.
+* `pytorch`: all the code for the legacy Pytorch theme (`qiskit_sphinx_theme`).
+* `ecosystem`: the code for the `qiskit-ecosystem` theme, which is built on top of the base `qiskit` theme. This folder only has overrides.
+* `theme`: static files, like HTML templates, for the `qiskit` theme.
 
 The top-level Python files are used for logic used by the theme, such as `translations.py` determining what URLs the HTML should use for translations support.
 
 ### `/example_docs`
 This subfolder contains a scaled down version of the Sphinx build that builds the documentation for the Qiskit repos. 
 
-It pulls styles from the `/src` subfolder. You can check any changes you are making to theme by building the documentation (see running locally section) and opening the HTML files generated in `example_docs/docs/_qiskit_build` and `example_docs/docs/_pytorch_build`.
+It pulls styles from the `/src` subfolder. You can check any changes you are making to theme by building the documentation (see running locally section) and opening the HTML files generated in `example_docs/docs/_qiskit_build`, `example_docs/docs/_ecosystem_build`, and `example_docs/docs/_pytorch_build`.
 
 ### `/docs_guide`
 This subfolder contains guidance on how to write documentation and build sphinx projects for Qiskit and Qiskit Ecosystem projects. You can view the fully rendered docs guide at https://qisk.it/docs-guide
@@ -38,10 +39,10 @@ This subfolder contains guidance on how to write documentation and build sphinx
 We use [Tox](https://tox.wiki/en/latest/), which you will need to install globally (e.g. using [`pipx`](https://pypa.github.io/pipx/)).
 
 * Run Python tests: `tox -e py`
-* Build `example_docs/` with the new Furo "Qiskit" theme:
+* Build `example_docs/` with the `qiskit` theme:
   1. `tox -e qiskit`
   2. Open up `example_docs/docs/_qiskit_build/index.html` in your browser
-* Build `example_docs/` with the work-in-progress Ecosystem theme:
+* Build `example_docs/` with the `qiskit-ecosystem` theme:
   1. `tox -e ecosystem`
   2. Open up `example_docs/docs/_ecosystem_build/index.html` in your browser
 * Build `example_docs/` with the legacy Pytorch theme:
@@ -136,10 +137,16 @@ Contributors with write access can also use live previews of the docs: GitHub wi
 ------
 ## FYI: How Furo Theme Inheritance Works
 
-We use Sphinx's inheritance future for our Furo theme, which we set in `theme/qiskit-sphinx-theme/theme.conf`. Sphinx will default to using all the files from Furo. But if we have a file with the same name as Furo, then Sphinx will use our copy. That allows us to override only what we care about.
+We use Sphinx's inheritance future for our Furo-based `qiskit` theme, which we set in `theme/qiskit-sphinx-theme/theme.conf`. Sphinx will default to using all the files from Furo. But if we have a file with the same name as Furo, then Sphinx will use our copy. That allows us to override only what we care about.
 
 We try to keep changes to a minimum because every divergence we make from base Furo increases our maintenance burden. Hence we prioritise only making changes that are important to the Qiskit brand. If the change would be generally useful to other users of Furo, we try to contribute upstream to the Furo project itself.
 
+The `qiskit-ecosystem` theme then inherits the `qiskit` theme to make some tweaks: 
+
+1. Adding back `brand.html` to the left sidebar, but with some custom code.
+2. Restoring Furo's `page.html` to remove the Qiskit top nav bar and restore the mobile header design.
+3. `qiskit-ecosystem.css` setting the Qiskit top nav bar height to 0px.
+
 ### How to change HTML
 Copy the HTML template from Furo and save it in the same file path. Then, at the top of the file, add this header:
 

README.md

@@ -1,20 +1,20 @@
-# qiskit_sphinx_theme
-The Sphinx theme for the Qiskit documentation.
+# qiskit-sphinx-theme
+The Sphinx themes for Qiskit and Qiskit Ecosystem documentation.
 
 ### Warning: new theme migration
 
-In qiskit-sphinx-theme 1.13, we migrated the theme from Pytorch to Furo, which brings several improvements. The old Pytorch theme will be removed in qiskit-sphinx-theme 2.0, which we expect to release in July or August 2023.
+In qiskit-sphinx-theme 1.13, we added the new `qiskit` theme, which migrates from Pytorch to Furo for several improvements. qiskit-sphinx-theme 1.14 added the `qiskit-ecosystem` theme. The old Pytorch theme will be removed in qiskit-sphinx-theme 2.0, which we expect to release in July or August 2023.
 
 See the section [Migrate from old Pytorch theme to new theme](#migrate-from-old-pytorch-theme-to-new-theme) for migration instructions.
 
 ## Overview
 
 This repository hosts three things: 
-- Qiskit Sphinx theme (located in the `src/` folder)
+- Qiskit Sphinx themes (located in the `src/` folder)
 - Example Docs (located in the `example_docs/` folder)
 - Qiskit Docs Guide (located in the `docs_guide/` folder)
 
-The Qiskit Sphinx Theme is the theme used by Qiskit Documentation (https://qiskit.org/documentation/) and Qiskit Ecosystem projects.
+The Qiskit Sphinx Themes are the themes used by Qiskit Documentation (https://qiskit.org/documentation/) and Qiskit Ecosystem projects.
 
 The Example Docs is a minimal Sphinx project that is used for testing the Qiskit Sphinx Theme. Every
 pull request will trigger [a GitHub workflow](https://github.com/Qiskit/qiskit_sphinx_theme/blob/main/.github/workflows/main.yml) that builds the Example Docs to make sure the changes do
@@ -34,9 +34,20 @@ pip install qiskit-sphinx-theme
 
 Then, set up the theme by updating `conf.py`:
 
-1. Set `html_theme = "qiskit"`
+1. Set `html_theme = "qiskit-ecosystem"` (only Qiskit Terra should use `qiskit`)
 2. Add `"qiskit_sphinx_theme"` to `extensions`
 
+You also likely want to set `html_title` in `conf.py`. This results in the left sidebar having a more useful and concise name, along with the page title in the browser. Most projects will want to use this in their `conf.py`:
+
+```python
+# Sphinx expects you to set these already.
+project = "My Project"
+release = "4.12"
+
+# This sets the title to e.g. `My Project 4.12`.
+html_title = f"{project} {release}"
+```
+
 ## Enable translations
 
 First, coordinate with the Translations team at https://github.com/qiskit-community/qiskit-translations to express your interest and to coordinate setting up the infrastructure.
@@ -102,7 +113,8 @@ The `qiskit_sphinx_theme` extension defines the below custom directives for you
 * `qiskit-card`
 * `qiskit-call-to-action-item` and `qiskit-call-to-action-grid`
 
-![Screenshot of examples of custom directives](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/9c672417-6451-4547-bc36-10709f7f3880)
+![](tests/js/qiskit.test.js-snapshots/custom-directives-1-linux.png)
+![](tests/js/qiskit.test.js-snapshots/custom-directives-2-linux.png)
 
 ## Enable Qiskit.org Analytics
 
@@ -120,19 +132,47 @@ By enabling analytics we will be able to collect information on number of visits
 
 If you do not enable analytics, no data will be collected and the `Was this page helpful?` component will not show.
 
+## Customize or disable the logo
+
+The `qiskit-ecosystem` theme includes the Qiskit Ecosystem logo by default.
+
+You can use 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"`.
+
+You can disable logos by setting `disable_ecosystem_logo` in `html_theme_options`, like this:
+
+```python
+html_theme_options = {
+    disable_ecosystem_logo=True,
+}
+```
+
+## IBM Projects: how to use blue color scheme
+
+By default, the `qiskit-ecosystem` theme uses purple as an accent color. Most projects should continue to use this, but certain highly IBM-affiliated projects like Qiskit IBM Runtime can change the accent color to blue by setting up `conf.py` like this:
+
+```python
+# Only intended for specific IBM projects.
+html_theme_options = {
+    "light_css_variables": {
+        "color-brand-primary": "var(--qiskit-color-blue)",
+    }
+}
+```
+
 ## Migrate from old Pytorch theme to new theme
 
-In qiskit-sphinx-theme 1.13, we migrated to a new Sphinx theme based on Furo, which is used by pip, Black, and attrs documentation. See https://github.com/Qiskit/qiskit_sphinx_theme/issues/232 for the motivation.
+In qiskit-sphinx-theme 1.13, we migrated to a new Sphinx theme called `qiskit`, which is based on Furo from the pip, Black, and attrs documentation. See https://github.com/Qiskit/qiskit_sphinx_theme/issues/232 for the motivation. qiskit-sphinx-theme 1.14 added the `qiskit-ecosystem` theme for Ecosystem projects.
+
+qiskit-sphinx-theme 1.13+ continues to support the legacy Pytorch theme, but support will be removed in version 2.0.
 
-qiskit-sphinx-theme 1.13 continues to support the legacy Pytorch theme, but support will be removed in version 2.0.
+To migrate, in `conf.py`:
 
-To migrate:
+1. Ensure that `"qiskit_sphinx_theme"` is in the `extensions` list.
+2. Set `html_theme = "qiskit-ecosystem"` rather than `"qiskit_sphinx_theme"`. (`qiskit` should only be used by Qiskit Terra.)
+3. Remove all `html_theme_options`.
+4. Remove `expandable_sidebar` from `html_context`, if set. If it was set, follow the below section [How to migrate expandable_sidebar](#how-to-migrate-expandable_sidebar).
 
-1. In `conf.py`, ensure that `"qiskit_sphinx_theme"` is in the `extensions` list.
-2. In `conf.py`, set `html_theme = "qiskit"` rather than `"qiskit_sphinx_theme"`.
-3. In `conf.py`, remove all `html_theme_options`.
-4. In `conf.py`, remove `expandable_sidebar` from `html_context`, if set. If it was set, follow the below section [How to migrate expandable_sidebar](#how-to-migrate-expandablesidebar).
-5. Render the docs and check that everything looks how expected. If not, please open a GitHub issue or reach out on Slack for help.
+Render the docs and check that everything looks how expected. If not, please open a GitHub issue or reach out on Slack for help.
 
 ### How to migrate expandable_sidebar
 
@@ -147,9 +187,9 @@ With the old theme, to have expandable folders, you had to have a dedicated `..
   Page 2 <page2>
 ```
 
-Instead, the new theme will render the `:caption:` as a top-level section header in the left sidebar, with top-level entries for each page. See the screenshot in the PR description of https://github.com/Qiskit/qiskit_sphinx_theme/pull/384 for an example of how the old theme renders `:caption:` and compare to [the new theme](https://github.com/Qiskit/qiskit_sphinx_theme/blob/main/tests/js/snapshots.test.js-snapshots/left-side-bar-renders-correctly-1-linux.png).
+Instead, the new theme will render the `:caption:` as a top-level section header in the left sidebar, with top-level entries for each page. See the screenshot in the PR description of https://github.com/Qiskit/qiskit_sphinx_theme/pull/384 for an example of how the old theme renders `:caption:` and compare to [the new theme](tests/js/qiskit.test.js-snapshots/left-side-bar-renders-correctly-1-linux.png).
 
-Additionally, the new theme renders pages with their own subpages as expandable folders, unlike the old theme. [For example](https://github.com/Qiskit/qiskit_sphinx_theme/blob/main/tests/js/snapshots.test.js-snapshots/left-side-bar-renders-correctly-1-linux.png), `<apidocs/index>` will include all subpages that are listed in the `.. toctree ::` of the page `apidocs/index.rst`.
+Additionally, the new theme renders pages with their own subpages as expandable folders, unlike the old theme. [For example](tests/js/qiskit.test.js-snapshots/left-side-bar-renders-correctly-1-linux.png), `<apidocs/index>` will include all subpages that are listed in the `.. toctree ::` of the page `apidocs/index.rst`.
 
 So, when migrating, you have to decide which behavior you want:
 

docs_guide/conf.py

@@ -21,7 +21,7 @@
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-html_theme = "_qiskit-ecosystem"
+html_theme = "qiskit-ecosystem"
 html_title = project
 
 intersphinx_mapping = {

example_docs/docs/conf.py

@@ -72,7 +72,7 @@
     }
     # Sets a better style for code syntax highlighting.
     pygments_style = "colorful"
-elif _THEME == "_qiskit-ecosystem":
+elif _THEME == "qiskit-ecosystem":
     # This tests out that ecosystem projects can change the color scheme.
     # Only specific IBM projects should set this! Most Ecosystem projects
     # should use the default of purple.

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 [project.entry-points."sphinx.html_themes"]
 qiskit = "qiskit_sphinx_theme"
 qiskit_sphinx_theme = "qiskit_sphinx_theme"
-_qiskit-ecosystem = "qiskit_sphinx_theme"
+qiskit-ecosystem = "qiskit_sphinx_theme"
 
 [project.urls]
 "Bug Tracker" = "https://github.com/Qiskit/qiskit_sphinx_theme/issues"

src/qiskit_sphinx_theme/__init__.py

@@ -107,7 +107,7 @@ def setup(app: sphinx.application.Sphinx) -> dict[str, bool]:
 
     app.add_html_theme("qiskit_sphinx_theme", _get_theme_absolute_path("pytorch"))
     app.add_html_theme("qiskit", _get_theme_absolute_path("theme/qiskit-sphinx-theme"))
-    app.add_html_theme("_qiskit-ecosystem", _get_theme_absolute_path("ecosystem"))
+    app.add_html_theme("qiskit-ecosystem", _get_theme_absolute_path("ecosystem"))
 
     app.connect("config-inited", activate_furo)
     app.connect("html-page-context", remove_furo_js, priority=600)

tox.ini

@@ -17,7 +17,7 @@ commands =
 [testenv:ecosystem]
 commands =
   sphinx-build -W --keep-going -j auto {posargs} example_docs/docs/ example_docs/docs/_ecosystem_build
-setenv = THEME=_qiskit-ecosystem
+setenv = THEME=qiskit-ecosystem
 
 [testenv:pytorch]
 commands =