Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use new Furo theme #1225

Merged
merged 8 commits into from
Jul 19, 2023
Merged

Use new Furo theme #1225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
b1bdbbc
try new theme
coruscating Jul 11, 2023
e930740
remove stubs from toctree for fast build
coruscating Jul 12, 2023
c4abfc7
add doc build options
coruscating Jul 13, 2023
390d79c
update build variables for production site
coruscating Jul 13, 2023
453e45e
update to official ecosystem theme
coruscating Jul 18, 2023
2dca0a1
update html_title and scripts
coruscating Jul 18, 2023
21494bf
remove unuseful comments
coruscating Jul 18, 2023
2ba6109
manually add gallery css file
coruscating Jul 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions docs/_static/nbsphinx-gallery.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
.nbsphinx-gallery {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add a comment explaining what's going on. Or even better, open a GitHub issue and link to it.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a comment here: https://github.com/Qiskit-Extensions/qiskit-experiments/blob/2ba6109e11fc086855d8360ad173a04f094dc7d4/docs/conf.py#L80

I can write an issue too.

display: grid;
grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
gap: 5px;
margin-top: 1em;
margin-bottom: 1em;
}

.nbsphinx-gallery>a {
padding: 5px;
border: 1px dotted currentColor;
border-radius: 2px;
text-align: center;
}

.nbsphinx-gallery>a:hover {
border-style: solid;
}

.nbsphinx-gallery img {
max-width: 100%;
max-height: 100%;
}

.nbsphinx-gallery>a>div:first-child {
display: flex;
align-items: start;
justify-content: center;
height: 120px;
margin-bottom: 5px;
}
37 changes: 18 additions & 19 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@

import os
import sys
import subprocess
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was an unused import.

import datetime

# -- Path setup --------------------------------------------------------------
Expand All @@ -36,9 +35,11 @@

# -- Project information -----------------------------------------------------
# The short X.Y version
version = "0.6"
version = os.getenv("VERSION_STRING", "0.6")

# The full version, including alpha/beta/rc tags
release = "0.6.0"
release = os.getenv("RELEASE_STRING", "0.6.0")

project = "Qiskit Experiments"
copyright = f"2021-{datetime.date.today().year}, Qiskit Development Team" # pylint: disable=redefined-builtin
author = "Qiskit Development Team"
Expand All @@ -65,10 +66,21 @@
"autodoc_analysis",
"autodoc_visualization",
"jupyter_execute_custom",
"sphinx_remove_toctrees",
]

# Remove stubs from the toctree by default because the full build is slow
# This is turned off for docs deployment
if not os.getenv("FULL_TOCTREE", None):
remove_from_toctrees = ["stubs/*"]

html_static_path = ["_static"]
templates_path = ["_templates"]
# Manually add the gallery CSS file for now
# TODO: Figure out why the styling is not working by default
html_css_files = [
"nbsphinx-gallery.css",
]

nbsphinx_timeout = 360
nbsphinx_execute = os.getenv("QISKIT_DOCS_BUILD_TUTORIALS", "never")
Expand Down Expand Up @@ -137,34 +149,21 @@
# package. Works only for the HTML builder currently.
modindex_common_prefix = ["qiskit_experiments."]

# -- Configuration for extlinks extension ------------------------------------
# Refer to https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "qiskit_sphinx_theme" # use the theme in subdir 'theme'
html_theme = "qiskit-ecosystem"

coruscating marked this conversation as resolved.
Show resolved Hide resolved
html_context = {
"analytics_enabled": True,
"expandable_sidebar": True,
}

html_title = f"{project} {release}"

docs_url_prefix = "ecosystem/experiments"

html_last_updated_fmt = "%Y/%m/%d"

html_theme_options = {
"logo_only": True,
"display_version": True,
"prev_next_buttons_location": "bottom",
"style_external_links": True,
}


autoclass_content = "both"
intersphinx_mapping = {
"matplotlib": ("https://matplotlib.org/stable/", None),
Expand Down
16 changes: 3 additions & 13 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,22 +92,12 @@ We've divided up the documentation into four sections with different purposes:

To the API reference

.. toctree::
:hidden:
:caption: Tutorials

All Tutorials <tutorials/index>
tutorials/intro
tutorials/getting_started
Calibrations <tutorials/calibrations>
Data Processor <tutorials/data_processor>
Curve Analysis <tutorials/curve_analysis>
Visualization <tutorials/visualization>
Custom Experiments <tutorials/custom_experiment>

.. toctree::
:hidden:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be hidden? Another option is to set :maxdepth: 1 or 2.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's supposed to be hidden or the entire ToC gets rendered after the page contents:
image

This toctree is only used to register those links for the sidebar.


Qiskit Experiments Home <self>
Getting Started <tutorials/getting_started>
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding Getting Started as a separate menu item to follow the recommended site structure: https://github.com/Qiskit/qiskit_sphinx_theme#tip-suggested-site-structure

tutorials/index
howtos/index
manuals/index
apidocs/index
Expand Down
5 changes: 3 additions & 2 deletions requirements-dev.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ astroid~=2.14.2 # Must be kept aligned to what pylint wants
jinja2==3.0.3
sphinx>=6.2.1,<=7
jupyter-sphinx>=0.4.0
qiskit-sphinx-theme~=1.12.0
qiskit-sphinx-theme~=1.14.0rc1
sphinx-design~=0.4.1
pygments>=2.4
reno>=4.0.0
Expand All @@ -24,4 +24,5 @@ coverage>=5.5
# Pin versions below because of build errors
ipykernel<=6.21.3
jupyter-client<=8.0.3
ipython<8.13.0 ; python_version<"3.9" # for python 3.8 compatibility
ipython<8.13.0 ; python_version<"3.9" # for python 3.8 compatibility
sphinx-remove-toctrees
2 changes: 1 addition & 1 deletion tools/deploy_documentation.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ sudo apt-get install -y ./rclone.deb
RCLONE_CONFIG_PATH=$(rclone config file | tail -1)

# Build the documentation.
tox -edocs
EXPERIMENTS_DEV_DOCS=1 FULL_TOCTREE=1 tox -edocs

echo "show current dir: "
pwd
Expand Down
2 changes: 1 addition & 1 deletion tools/deploy_documentation_dev.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ sudo apt-get install -y ./rclone.deb
RCLONE_CONFIG_PATH=$(rclone config file | tail -1)

# Build the documentation.
EXPERIMENTS_DEV_DOCS=1 tox -edocs
EXPERIMENTS_DEV_DOCS=1 FULL_TOCTREE=1 RELEASE_STRING=`git describe` tox -edocs

echo "show current dir: "
pwd
Expand Down
18 changes: 15 additions & 3 deletions tox.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,19 +67,31 @@ commands = black {posargs} qiskit_experiments test tools setup.py

[testenv:docs]
usedevelop = False
passenv = EXPERIMENTS_DEV_DOCS
passenv =
EXPERIMENTS_DEV_DOCS
FULL_TOCTREE
RELEASE_STRING
VERSION_STRING
commands =
sphinx-build -T -W --keep-going -b html {posargs} docs/ docs/_build/html

[testenv:docs-parallel]
usedevelop = False
passenv = EXPERIMENTS_DEV_DOCS
passenv =
EXPERIMENTS_DEV_DOCS
FULL_TOCTREE
RELEASE_STRING
VERSION_STRING
commands =
sphinx-build -j auto -T -W --keep-going -b html {posargs} docs/ docs/_build/html

[testenv:docs-minimal]
usedevelop = False
passenv = EXPERIMENTS_DEV_DOCS
passenv =
EXPERIMENTS_DEV_DOCS
FULL_TOCTREE
RELEASE_STRING
VERSION_STRING
setenv =
QISKIT_DOCS_SKIP_EXECUTE = 1
commands =
Expand Down