From a90f67636707c4c0393acf150f447ca3fed8d5ef Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Sat, 24 Jul 2021 01:59:12 -0400 Subject: [PATCH 1/7] Add a release mode for docs This toggles defaults for the image compression, HiDPI images, theme navigation, and analytics. --- doc/conf.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 8c010bd71cba..9e750efad671 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -22,6 +22,9 @@ from datetime import datetime import time +# Release mode enables optimizations and other related options. +_doc_release_mode = tags.has('release') # noqa + # are we running circle CI? CIRCLECI = 'CIRCLECI' in os.environ @@ -175,10 +178,10 @@ def _check_dependencies(): 'remove_config_comments': True, 'min_reported_time': 1, 'thumbnail_size': (320, 224), - 'compress_images': () if CIRCLECI else ('thumbnails', 'images'), + 'compress_images': ('thumbnails', 'images') if _doc_release_mode else (), 'matplotlib_animations': True, - # 3.7 CI doc build should not use hidpi images during the testing phase - 'image_srcset': [] if sys.version_info[:2] == (3, 7) else ["2x"], + # Doc build should not use hidpi images during the testing phase. + 'image_srcset': ["2x"] if _doc_release_mode else [], 'junit': '../test-results/sphinx-gallery/junit.xml' if CIRCLECI else '', } @@ -293,7 +296,7 @@ def _check_dependencies(): html_logo = "_static/logo2.svg" html_theme_options = { "logo_link": "index", - "collapse_navigation": True if CIRCLECI else False, + "collapse_navigation": not _doc_release_mode, "icon_links": [ { "name": "gitter", @@ -319,7 +322,7 @@ def _check_dependencies(): "show_prev_next": False, "navbar_center": ["mpl_nav_bar.html"], } -include_analytics = False +include_analytics = _doc_release_mode if include_analytics: html_theme_options["google_analytics_id"] = "UA-55954603-1" From db08fccc7c6524ca12e98a76e3fed021fdc4cbf9 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Sat, 24 Jul 2021 04:13:53 -0400 Subject: [PATCH 2/7] Check that the new sphinx theme is available early --- doc/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/conf.py b/doc/conf.py index 9e750efad671..6636cc796308 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -91,6 +91,7 @@ def _check_dependencies(): "matplotlib": 'matplotlib', "numpydoc": 'numpydoc', "PIL.Image": 'pillow', + "pydata_sphinx_theme": 'pydata_sphinx_theme', "sphinx_copybutton": 'sphinx_copybutton', "sphinx_gallery": 'sphinx_gallery', "sphinxcontrib.inkscapeconverter": 'sphinxcontrib-svg2pdfconverter', From 76d4a3ef38ad968cd8f1c9dacc7d7df2a2bead6b Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Sat, 24 Jul 2021 04:56:14 -0400 Subject: [PATCH 3/7] DOC: Disable extra plot formats if not release mode --- doc/conf.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index 6636cc796308..ed65d780ce95 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -542,6 +542,18 @@ def _check_dependencies(): # graphviz_output_format = 'svg' +def reduce_plot_formats(app): + if app.builder.name == 'html': + keep = 'png' + elif app.builder.name == 'latex': + keep = 'pdf' + else: + return + app.config.plot_formats = [entry + for entry in app.config.plot_formats + if entry[0] == keep] + + def setup(app): if any(st in version for st in ('post', 'alpha', 'beta')): bld_type = 'dev' @@ -549,6 +561,9 @@ def setup(app): bld_type = 'rel' app.add_config_value('releaselevel', bld_type, 'env') + if not _doc_release_mode: + app.connect('builder-inited', reduce_plot_formats) + # ----------------------------------------------------------------------------- # Source code links # ----------------------------------------------------------------------------- From f09213da7cc7763cfcce74adc0bbaba0f09bb9f1 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Sat, 24 Jul 2021 05:01:29 -0400 Subject: [PATCH 4/7] Update release guide with new release tag --- doc/devel/release_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index 612ee423590e..423b2ba51b2c 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -345,7 +345,7 @@ build the docs from the ``ver-doc`` branch. An easy way to arrange this is:: pip install -r requirements/doc/doc-requirements.txt git checkout v2.0.0-doc git clean -xfd - make -Cdoc O="-Ainclude_analytics=True -j$(nproc)" html latexpdf LATEXMKOPTS="-silent -f" + make -Cdoc O="-t release -j$(nproc)" html latexpdf LATEXMKOPTS="-silent -f" which will build both the html and pdf version of the documentation. From 61727eb289895e5523d778042ad602f2e4394682 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Sat, 24 Jul 2021 05:08:50 -0400 Subject: [PATCH 5/7] DOC: Set release mode when deploying devdocs only But not for PRs. --- .circleci/config.yml | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 4a0f262a4eb7..93335b41bbac 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -124,15 +124,13 @@ commands: command: | # Set epoch to date of latest tag. export SOURCE_DATE_EPOCH="$(git log -1 --format=%at $(git describe --abbrev=0))" - # Include analytics only when deploying to devdocs. - if [ "$CIRCLE_PROJECT_USERNAME" != "matplotlib" ] || \ - [ "$CIRCLE_BRANCH" != "master" ] || \ - [[ "$CIRCLE_PULL_REQUEST" == https://github.com/matplotlib/matplotlib/pull/* ]]; then - export ANALYTICS=False - else - export ANALYTICS=True + # Set release mode only when deploying to devdocs. + if [ "$CIRCLE_PROJECT_USERNAME" = "matplotlib" ] && \ + [ "$CIRCLE_BRANCH" = "master" ] && \ + [ "$CIRCLE_PR_NUMBER" = "" ]; then + export RELEASE_TAG='-t release' fi - make html O="-T -Ainclude_analytics=$ANALYTICS" + make html O="-T $RELEASE_TAG" rm -r build/html/_sources working_directory: doc - save_cache: From 3e29c6941a9948760ceae80675af34e09897b9d8 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Tue, 28 Sep 2021 00:02:57 -0400 Subject: [PATCH 6/7] DOC: Always create HiDPI images --- doc/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index ed65d780ce95..08a944c39dd2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -181,8 +181,7 @@ def _check_dependencies(): 'thumbnail_size': (320, 224), 'compress_images': ('thumbnails', 'images') if _doc_release_mode else (), 'matplotlib_animations': True, - # Doc build should not use hidpi images during the testing phase. - 'image_srcset': ["2x"] if _doc_release_mode else [], + 'image_srcset': ["2x"], 'junit': '../test-results/sphinx-gallery/junit.xml' if CIRCLECI else '', } From 5d9b312457f8e6faaaf3f267dba9b1ae7981839a Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Wed, 29 Sep 2021 22:05:30 -0400 Subject: [PATCH 7/7] Apply changes from review --- doc/conf.py | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 08a944c39dd2..7774b0f726eb 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -23,7 +23,7 @@ import time # Release mode enables optimizations and other related options. -_doc_release_mode = tags.has('release') # noqa +is_release_build = tags.has('release') # noqa # are we running circle CI? CIRCLECI = 'CIRCLECI' in os.environ @@ -179,7 +179,8 @@ def _check_dependencies(): 'remove_config_comments': True, 'min_reported_time': 1, 'thumbnail_size': (320, 224), - 'compress_images': ('thumbnails', 'images') if _doc_release_mode else (), + # Compression is a significant effort that we skip for local and CI builds. + 'compress_images': ('thumbnails', 'images') if is_release_build else (), 'matplotlib_animations': True, 'image_srcset': ["2x"], 'junit': '../test-results/sphinx-gallery/junit.xml' if CIRCLECI else '', @@ -296,7 +297,9 @@ def _check_dependencies(): html_logo = "_static/logo2.svg" html_theme_options = { "logo_link": "index", - "collapse_navigation": not _doc_release_mode, + # collapse_navigation in pydata-sphinx-theme is slow, so skipped for local + # and CI builds https://github.com/pydata/pydata-sphinx-theme/pull/386 + "collapse_navigation": not is_release_build, "icon_links": [ { "name": "gitter", @@ -322,7 +325,7 @@ def _check_dependencies(): "show_prev_next": False, "navbar_center": ["mpl_nav_bar.html"], } -include_analytics = _doc_release_mode +include_analytics = is_release_build if include_analytics: html_theme_options["google_analytics_id"] = "UA-55954603-1" @@ -542,6 +545,8 @@ def _check_dependencies(): def reduce_plot_formats(app): + # Fox CI and local builds, we don't need all the default plot formats, so + # only generate the directly useful one for the current builder. if app.builder.name == 'html': keep = 'png' elif app.builder.name == 'latex': @@ -560,7 +565,7 @@ def setup(app): bld_type = 'rel' app.add_config_value('releaselevel', bld_type, 'env') - if not _doc_release_mode: + if not is_release_build: app.connect('builder-inited', reduce_plot_formats) # -----------------------------------------------------------------------------