Merge pull request matplotlib#20730 from QuLogic/doc-release-mode

DOC: Add a release mode tag

Author: timhoffm

.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:

doc/conf.py

@@ -22,6 +22,9 @@
 from datetime import datetime
 import time
 
+# Release mode enables optimizations and other related options.
+is_release_build = tags.has('release')  # noqa
+
 # are we running circle CI?
 CIRCLECI = 'CIRCLECI' in os.environ
 
@@ -88,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',
@@ -175,10 +179,10 @@ def _check_dependencies():
     'remove_config_comments': True,
     'min_reported_time': 1,
     'thumbnail_size': (320, 224),
-    'compress_images': () if CIRCLECI else ('thumbnails', 'images'),
+    # 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,
-    # 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"],
+    'image_srcset': ["2x"],
     'junit': '../test-results/sphinx-gallery/junit.xml' if CIRCLECI else '',
 }
 
@@ -293,7 +297,9 @@ def _check_dependencies():
 html_logo = "_static/logo2.svg"
 html_theme_options = {
     "logo_link": "index",
-    "collapse_navigation": True if CIRCLECI else False,
+    # 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",
@@ -319,7 +325,7 @@ def _check_dependencies():
     "show_prev_next": False,
     "navbar_center": ["mpl_nav_bar.html"],
 }
-include_analytics = False
+include_analytics = is_release_build
 if include_analytics:
     html_theme_options["google_analytics_id"] = "UA-55954603-1"
 
@@ -538,13 +544,30 @@ def _check_dependencies():
 # graphviz_output_format = 'svg'
 
 
+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':
+        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'
     else:
         bld_type = 'rel'
     app.add_config_value('releaselevel', bld_type, 'env')
 
+    if not is_release_build:
+        app.connect('builder-inited', reduce_plot_formats)
+
 # -----------------------------------------------------------------------------
 # Source code links
 # -----------------------------------------------------------------------------

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.