diff --git a/docs/_static/nbsphinx-gallery.css b/docs/_static/nbsphinx-gallery.css new file mode 100644 index 0000000000..f60c7b591f --- /dev/null +++ b/docs/_static/nbsphinx-gallery.css @@ -0,0 +1,31 @@ +.nbsphinx-gallery { + 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; +} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 0570307794..19ee150827 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,7 +16,6 @@ import os import sys -import subprocess import datetime # -- Path setup -------------------------------------------------------------- @@ -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" @@ -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") @@ -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" 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), diff --git a/docs/index.rst b/docs/index.rst index b1bfa7c5e5..93a2879d63 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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/intro - tutorials/getting_started - Calibrations - Data Processor - Curve Analysis - Visualization - Custom Experiments - .. toctree:: :hidden: + Qiskit Experiments Home + Getting Started + tutorials/index howtos/index manuals/index apidocs/index diff --git a/requirements-dev.txt b/requirements-dev.txt index d60ab33020..23cc0048b2 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -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 @@ -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 \ No newline at end of file +ipython<8.13.0 ; python_version<"3.9" # for python 3.8 compatibility +sphinx-remove-toctrees \ No newline at end of file diff --git a/tools/deploy_documentation.sh b/tools/deploy_documentation.sh index 597ac7d873..f6f1ef3c5a 100755 --- a/tools/deploy_documentation.sh +++ b/tools/deploy_documentation.sh @@ -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 diff --git a/tools/deploy_documentation_dev.sh b/tools/deploy_documentation_dev.sh index 69e167c2bf..53fb8c3f2a 100755 --- a/tools/deploy_documentation_dev.sh +++ b/tools/deploy_documentation_dev.sh @@ -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 diff --git a/tox.ini b/tox.ini index ea93fa0814..7bebeacfb6 100644 --- a/tox.ini +++ b/tox.ini @@ -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 =