From c7e66f6c402c576bc786254b853d83ca8578ae2d Mon Sep 17 00:00:00 2001 From: Eric Arellano Date: Wed, 28 Jun 2023 07:11:07 -0600 Subject: [PATCH 1/4] Add `qiskit` theme based on Furo --- .github/workflows/main.yml | 2 +- CONTRIBUTING.md | 10 +- Dockerfile | 2 +- README.md | 144 +++++++++------------------- example_docs/docs/conf.py | 4 +- pyproject.toml | 2 +- src/qiskit_sphinx_theme/__init__.py | 4 +- 7 files changed, 55 insertions(+), 113 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f20ddd7d..8b87607f 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -54,7 +54,7 @@ jobs: rm -rf example_docs/_build_legacy - name: Build Furo theme run: | - THEME=_qiskit_furo tox run -e docs + THEME=qiskit tox run -e docs tar -zcvf furo_html_docs.tar.gz example_docs/docs/_build/html mv furo_html_docs.tar.gz artifacts/. - name: Upload Sphinx builds diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11106c5e..7d68df6c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,7 +48,7 @@ We use [Tox](https://tox.wiki/en/latest/), which you will need to install global Sometimes Sphinx's caching can get in a bad state. First, try running `tox -e docs-clean`, which will remove Sphinx's cache. If you are still having issues, try adding `-r` your command, e.g. `tox -e docs -r`. `-r` tells Tox to reinstall the dependencies. -We are in the process of migrating our theme from Pytorch to Furo (see https://github.com/Qiskit/qiskit_sphinx_theme/issues/232). To build the local docs using the Furo theme, use `THEME=_qiskit_furo` in front of the command, e.g. `THEME=_qiskit_furo tox -e docs`. +We migrated the theme from Pytorch to Furo (see https://github.com/Qiskit/qiskit_sphinx_theme/issues/232). To build the legacy Pytorch theme, use `THEME=qiskit_sphinx_theme` in front of the command, e.g. `THEME=qiskit_sphinx_theme tox -e docs`. ------ ## Visual regression testing @@ -84,10 +84,10 @@ First, you need to install: Then, to run the tests locally: 1. `npm install` -2. Build the docs with Furo, `THEME=_qiskit_furo tox -e docs` +2. Build the docs, `tox -e docs` 3. `npm run test-snapshots` -You must rebuild the docs with `THEME=_qiskit_furo tox -e docs` whenever you make changes to the theme or docs folder. The docs will not automatically rebuild. +You must rebuild the docs with `tox -e docs` whenever you make changes to the theme or docs folder. The docs will not automatically rebuild. ### How to update the expected snapshot for intentional changes @@ -107,7 +107,7 @@ To update the top nav bar web component: 2. There should be a file created at the root of the web components repository called `experimental-bundled-ui-shell.js`. Copy its contents into these files in this theme repository: 1. `src/qiskit_sphinx_theme/pytorch/static/js/web-components/top-nav-bar.js` 2. `src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/js/web-components/top-nav-bar.js` -3. Build the example docs with `tox -e docs` and `THEME=_qiskit_furo tox -e docs` to ensure everything works. +3. Build the example docs with `tox -e docs` and `THEME=qiskit_sphinx_theme tox -e docs` to ensure everything works. If you want to add a new web component: @@ -115,7 +115,7 @@ If you want to add a new web component: 2. Add the file contents to the `src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/js/web-components/` folder in this theme repository. (We shouldn't add web components to Pytorch.) 3. Load the web component in `extra_head.html` with a line like ``. 4. Use the web component element in the relevant HTML, e.g. `` in `layout.html`. Remember to surround the change with a `QISKIT CHANGE:` comment. -5. Build the example docs with `THEME=_qiskit_furo tox -e docs` to ensure everything works. +5. Build the example docs with `tox -e docs` to ensure everything works. 6. Update this guide with specific instructions for the web component. ------ diff --git a/Dockerfile b/Dockerfile index 53bfcfc3..ddbaacea 100644 --- a/Dockerfile +++ b/Dockerfile @@ -15,7 +15,7 @@ WORKDIR /app COPY . . -RUN THEME=_qiskit_furo tox run -e docs +RUN tox run -e docs EXPOSE 8000 CMD ["python", "-m", "http.server", "-d", "example_docs/docs/_build/html"] diff --git a/README.md b/README.md index 3523552a..37f92c3a 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,11 @@ The Sphinx theme for the Qiskit documentation. ## Overview This repository hosts three things: -- Qiskit Sphinx theme (located in the [qiskit_sphinx_theme](/qiskit_sphinx_theme) folder) -- Example Docs (located in the [example_docs](/example_docs) folder) -- Qiskit Docs Guide (located in the [docs_guide](/docs_guide) folder) +- Qiskit Sphinx theme (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/) site. It contains mainly front end elements that -gives the Qiskit design style. +The Qiskit Sphinx Theme is the theme 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 @@ -30,100 +28,9 @@ pip install qiskit-sphinx-theme Then, set up the theme by updating `conf.py`: -1. Set `html_theme = "qiskit_sphinx_theme"` +1. Set `html_theme = "qiskit"` 2. Add `"qiskit_sphinx_theme"` to `extensions` -## Configure Left Sidebar - -To keep UX/UI similar across different Qiskit packages we strongly encourage the following structure for you sidebar, which can be set in the toctree of your `index.rst`: - -```rst -.. toctree:: - :hidden: - - Documentation Home - Getting Started - Tutorials - How-to Guides - API Reference - Explanations - Release Notes - GitHub -``` - -The above toctree will render a sidebar that looks like the image below: - -Screenshot 2023-02-09 at 12 13 52 PM - -Each item in the toctree corresponds to a single `.rst` file, and can use internal links or external. External links will have a "new tab" icon rendered next to them. - -Screenshot 2023-02-09 at 12 14 45 PM - -In addition to the pages in the toctree, the sidebar also adds: -- (optional) a separate dropdown menu *at the top* with different languages, but only if you have a `translations_list` setup in your `html_context` in your `conf.py` corresponding logic in a `version_utils.py`. -- (optional) a dropdown *at the bottom* with links to previous releases, if you have a `version_list` setup in your `html_context` in your `conf.py` and corresponding logic in a `version_utils.py`. - -### Add Expandable Items to Sidebar - -You may want to configure your documentation to include expandable items in the sidebar, for example: - -Screenshot 2023-02-09 at 12 29 13 PM - -To configure your documentation to use exapandable sidebar headings like the example above you must do the following: -1. Add a `expandable_sidebar` variable to the `html_context` object in your `conf.py` and set the value to `True`: - ```python - html_context = { - 'expandable_sidebar': True - } - ``` -2. Refactor the `toctree` in your `index.rst` to separate your pages into different sections. Sections that include a `:caption:` directive will be turned into expandable sidebar sections, with the caption forming the title of the dropdown. for example, to render the expandable sidebar shown above your `toctree` in your `index.rst` should look like this: - ```rst - .. toctree:: - :hidden: - - Documentation Home - Getting Started - - .. toctree:: - :hidden: - :caption: Tutorials - - Tutorial 1 - Tutorial 2 - Tutorial 3 > - All Tutorials - - .. toctree:: - :hidden: - :glob: - :caption: How-to Guides - - how_tos/* - - .. toctree:: - :hidden: - :glob: - :caption: API Reference - - apidocs/* - - .. toctree:: - :hidden: - :glob: - :caption: Explanations - - expalanations/* - - .. toctree:: - :hidden: - - Release Notes - GitHub - ``` - - -*Tip: if you want to add all files in a sub-directory to your expandable dropdown section you can use the `:glob:` directive instead of listing out each page (see example above for the How-to Guides, API Reference and Explanations sections). This will list out each page in alphabetical order, so if you want a specific order you will need to list the pages out individually in the `toctree` (see example above for the Tutorials section)* - ## 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. @@ -193,7 +100,7 @@ The `qiskit_sphinx_theme` extension defines the below custom directives for you ## Enable Qiskit.org Analytics -Qiskit.org uses Segment Analytics to collect information on traffic to sites under the qiskit.org domain. This is not enabled by default but if you would like to enable it you can add a `analytics_enabled` variable to the `html_context` object in your `conf.py`. Setting this to `True` will enable analytics for your site once it is deployed to `qiskit.org/documentation`. +Qiskit.org uses Segment Analytics to collect information on traffic to sites under the qiskit.org domain. This is not enabled by default but if you would like to enable it you can add a `analytics_enabled` variable to the `html_context` object in your `conf.py`. Setting this to `True` will enable analytics for your site once it is deployed to `qiskit.org/`. ```python html_context = { @@ -203,7 +110,42 @@ html_context = { By enabling analytics we will be able to collect information on number of visits to each documentation page. It will also trigger the addition of a `Was this page helpful?` component at the bottom of each documentation page, so users will be able to provide yes/no feedback for each page. -Screenshot 2022-11-14 at 11 28 11 AM +![](tests/js/snapshots.test.js-snapshots/footer-includes-page-analytics-1-linux.png) + +If you do not enable analytics, no data will be collected and the `Was this page helpful?` component will not show. + +## 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. + +qiskit-sphinx-theme 1.13 continues to support the legacy Pytorch theme, but support will be removed in version 2.0. + +To migrate: + +1. In `conf.py`, set `html_theme = "qiskit"` rather than `"qiskit_sphinx_theme"`. +2. In `conf.py`, remove all `html_theme_options`. +3. In `conf.py`, remove `expandable_sidebar` from `html_context`, if set. +4. If `expandable_sidebar` was enabled, then update your `index.rst` files. The new theme always has expandable sidebars. Before, you had to have a dedicated `.. toctree::` directive for each expandable folder, along with the `:caption:` option set to the folder name. To migrate, consolidate all of your `.. toctree::` directives into one. Alternatively, you can keep the separate `.. toctree::` entries; the `:caption:` will render as a top-level header and the folder contents will be expanded. +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. + +Reminder: you do not have to migrate to the `qiskit` theme until qiskit-sphinx-theme 2.0. For example, you can migrate but rollback to `qiskit_sphinx_theme` if you discover there is an issue. + +## Tip: suggested site structure -If you do not enable analytics no data will be collected and the `Was this page helpful?` component will not show. +To keep UX/UI similar across different Qiskit packages, we encourage the following structure for you sidebar, which can be set in the toctree of your `index.rst`: +```rst +.. toctree:: + :hidden: + + Documentation Home + Getting Started + Tutorials + How-to Guides + API Reference + Explanations + Release Notes + GitHub +``` + +Each item in the toctree corresponds to a single `.rst` file, and can use internal links or external. External links will have a "new tab" icon rendered next to them. diff --git a/example_docs/docs/conf.py b/example_docs/docs/conf.py index ee53f37a..f55ae136 100644 --- a/example_docs/docs/conf.py +++ b/example_docs/docs/conf.py @@ -49,10 +49,10 @@ # This allows us to test both the Furo and Pytorch themes. In normal repositories, `html_theme` # would be set to one specific theme. -_THEME = os.getenv("THEME", "qiskit_sphinx_theme") +_THEME = os.getenv("THEME", "qiskit") html_theme = _THEME -if _THEME != "_qiskit_furo": +if _THEME == "qiskit_sphinx_theme": html_theme_options = { "logo_only": True, "display_version": True, diff --git a/pyproject.toml b/pyproject.toml index 481f35c1..80424a8a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -33,8 +33,8 @@ dependencies = [ ] [project.entry-points."sphinx.html_themes"] +qiskit = "qiskit_sphinx_theme" qiskit_sphinx_theme = "qiskit_sphinx_theme" -_qiskit_furo = "qiskit_sphinx_theme" [project.urls] "Bug Tracker" = "https://github.com/Qiskit/qiskit_sphinx_theme/issues" diff --git a/src/qiskit_sphinx_theme/__init__.py b/src/qiskit_sphinx_theme/__init__.py index f81d1312..b16dedca 100644 --- a/src/qiskit_sphinx_theme/__init__.py +++ b/src/qiskit_sphinx_theme/__init__.py @@ -68,7 +68,7 @@ def remove_thebe_if_not_needed( def activate_themes(app: sphinx.application.Sphinx, config: sphinx.config.Config) -> None: - if config.html_theme == "_qiskit_furo": + if config.html_theme == "qiskit": # We set a low priority so that our Qiskit CSS file overrides Furo. app.add_css_file("styles/furo.css", 100) app.add_js_file("scripts/furo.js") @@ -92,7 +92,7 @@ def setup(app: sphinx.application.Sphinx) -> dict[str, bool]: translations.setup(app) app.add_html_theme("qiskit_sphinx_theme", _get_theme_absolute_path("pytorch")) - app.add_html_theme("_qiskit_furo", _get_theme_absolute_path("theme/qiskit-sphinx-theme")) + app.add_html_theme("qiskit", _get_theme_absolute_path("theme/qiskit-sphinx-theme")) app.connect("html-page-context", remove_thebe_if_not_needed) app.connect("config-inited", activate_themes) From 5fd089bdd6b5a6f93dafd41796c78bee943fe004 Mon Sep 17 00:00:00 2001 From: Eric Arellano Date: Fri, 30 Jun 2023 08:46:40 -0600 Subject: [PATCH 2/4] Review feedback --- CONTRIBUTING.md | 2 +- README.md | 39 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 37 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d68df6c..613c089b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,7 +48,7 @@ We use [Tox](https://tox.wiki/en/latest/), which you will need to install global Sometimes Sphinx's caching can get in a bad state. First, try running `tox -e docs-clean`, which will remove Sphinx's cache. If you are still having issues, try adding `-r` your command, e.g. `tox -e docs -r`. `-r` tells Tox to reinstall the dependencies. -We migrated the theme from Pytorch to Furo (see https://github.com/Qiskit/qiskit_sphinx_theme/issues/232). To build the legacy Pytorch theme, use `THEME=qiskit_sphinx_theme` in front of the command, e.g. `THEME=qiskit_sphinx_theme tox -e docs`. +We migrated the theme from Pytorch to Furo in qiskit-sphinx-theme 1.13 (see https://github.com/Qiskit/qiskit_sphinx_theme/issues/232). Pytorch will be removed in 2.0. To build the legacy Pytorch theme, use `THEME=qiskit_sphinx_theme` in front of the command, e.g. `THEME=qiskit_sphinx_theme tox -e docs`. ------ ## Visual regression testing diff --git a/README.md b/README.md index 74ff0127..f652fd35 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ # qiskit_sphinx_theme The Sphinx theme for the Qiskit 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. + +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: @@ -124,12 +130,39 @@ To migrate: 1. In `conf.py`, set `html_theme = "qiskit"` rather than `"qiskit_sphinx_theme"`. 2. In `conf.py`, remove all `html_theme_options`. -3. In `conf.py`, remove `expandable_sidebar` from `html_context`, if set. -4. If `expandable_sidebar` was enabled, then update your `index.rst` files. The new theme always has expandable sidebars. Before, you had to have a dedicated `.. toctree::` directive for each expandable folder, along with the `:caption:` option set to the folder name. To migrate, consolidate all of your `.. toctree::` directives into one. Alternatively, you can keep the separate `.. toctree::` entries; the `:caption:` will render as a top-level header and the folder contents will be expanded. -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. +3. 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). +4. Render the docs and check that everything looks how expected. If not, please open a GitHub issue or reach out on Slack for help. Reminder: you do not have to migrate to the `qiskit` theme until qiskit-sphinx-theme 2.0. For example, you can migrate but rollback to `qiskit_sphinx_theme` if you discover there is an issue. +### How to migrate expandable_sidebar + +With the old theme, to have expandable folders, you had to have a dedicated `.. toctree ::` directive with a `:caption:` option, like this: + +```rst +.. toctree:: + :caption: My Folder + :hidden: + + Page 1 + Page 2 +``` + +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). + +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), `` 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: + +- Use the new theme's style. No changes necessary. +- Use the new theme's style, but get rid of the top level section header. To implement: + 1. Consolidate the `.. toctree ::` directive with earlier ones so that they are all in the same `toctree`. +- Keep the `:caption:` as an expandable folder, rather than a top-level section header. To implement: + 1. Create a new directory and RST file like `my_folder/index.rst`. + 2. Move the `.. toctree::` directive to that page. + 3. Get rid of the `:caption:` option. + 4. Link to the new file `my_folder/index.rst` in the parent `index.rst` by adding it to a `.. toctree ::` in the parent. + ## Tip: suggested site structure To keep UX/UI similar across different Qiskit packages, we encourage the following structure for you sidebar, which can be set in the toctree of your `index.rst`: From 0582e779d6ff0fd4e2a46f4a66e5d28d466bcbfb Mon Sep 17 00:00:00 2001 From: Eric Arellano Date: Fri, 30 Jun 2023 09:08:29 -0600 Subject: [PATCH 3/4] mention extensions list --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f652fd35..9a482808 100644 --- a/README.md +++ b/README.md @@ -128,10 +128,11 @@ qiskit-sphinx-theme 1.13 continues to support the legacy Pytorch theme, but supp To migrate: -1. In `conf.py`, set `html_theme = "qiskit"` rather than `"qiskit_sphinx_theme"`. -2. In `conf.py`, remove all `html_theme_options`. -3. 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). -4. Render the docs and check that everything looks how expected. If not, please open a GitHub issue or reach out on Slack for help. +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. Reminder: you do not have to migrate to the `qiskit` theme until qiskit-sphinx-theme 2.0. For example, you can migrate but rollback to `qiskit_sphinx_theme` if you discover there is an issue. From e087ce4b7ac362609341cfa7716d39248e1f1397 Mon Sep 17 00:00:00 2001 From: Eric Arellano Date: Fri, 30 Jun 2023 09:57:37 -0600 Subject: [PATCH 4/4] Remove note about rolling back --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 9a482808..37ce3063 100644 --- a/README.md +++ b/README.md @@ -134,8 +134,6 @@ To migrate: 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. -Reminder: you do not have to migrate to the `qiskit` theme until qiskit-sphinx-theme 2.0. For example, you can migrate but rollback to `qiskit_sphinx_theme` if you discover there is an issue. - ### How to migrate expandable_sidebar With the old theme, to have expandable folders, you had to have a dedicated `.. toctree ::` directive with a `:caption:` option, like this: