sphinx-gallery · lucyleeow · Aug 26, 2022 · Jul 30, 2022 · Jul 30, 2022 · Jul 30, 2022
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -13,7 +13,7 @@ jobs:
             sudo apt-get --no-install-recommends install -yq \
               libosmesa6 libglx-mesa0 libopengl0 libglx0 libdbus-1-3 \
               libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 libxcb-xinerama0 \
-              texlive texlive-latex-extra latexmk optipng tex-gyre
+              texlive texlive-latex-extra latexmk optipng tex-gyre graphviz
             sudo ln -s /usr/lib/x86_64-linux-gnu/libxcb-util.so.0 /usr/lib/x86_64-linux-gnu/libxcb-util.so.1
       - run:
           name: Merge with upstream
@@ -41,7 +41,7 @@ jobs:
           # PyVista 0.33 needs VTK >= 9.0.1, but Mayavi breaks with 9.1... so just pin PyVista for now
           command: |
             pip install --progress-bar off --only-binary ":all:" numpy matplotlib "pyqt5!=5.15.2,!=5.15.3" "vtk<=9.0.1"
-            pip install --progress-bar off --user seaborn statsmodels sphinx_rtd_theme pillow joblib sphinx pytest "traits<6.3.0" mayavi "pyvista<0.33" memory_profiler ipython plotly
+            pip install --progress-bar off --user seaborn statsmodels sphinx_rtd_theme pillow joblib sphinx pytest "traits<6.3.0" mayavi "pyvista<0.33" memory_profiler ipython plotly graphviz
       - save_cache:
           key: cache-pip
           paths:

diff --git a/continuous_integration/azure/install.sh b/continuous_integration/azure/install.sh
@@ -15,7 +15,7 @@ if [ "$DISTRIB" == "conda" ]; then
     echo "##vso[task.prependpath]$CONDA/bin"
     export PATH=${CONDA}/bin:${PATH}
     CONDA_TO_INSTALL="$@"
-    CONDA_TO_INSTALL="$CONDA_TO_INSTALL python=$PYTHON_VERSION pip numpy setuptools matplotlib pillow pytest pytest-cov coverage seaborn statsmodels 'plotly>=4.0' joblib flake8 wheel libiconv"
+    CONDA_TO_INSTALL="$CONDA_TO_INSTALL python=$PYTHON_VERSION pip numpy setuptools matplotlib pillow pytest pytest-cov coverage seaborn statsmodels 'plotly>=4.0' joblib flake8 wheel libiconv graphviz"
     PIP_DEPENDENCIES="$@"
     PIP_DEPENDENCIES="$PIP_DEPENDENCIES sphinx_rtd_theme check-manifest"
     if [ "$PYTHON_VERSION" != "3.7" -o "$LOCALE" != "C" ]; then
@@ -62,7 +62,7 @@ elif [ "$DISTRIB" == "nightly" ]; then
 elif [ "$DISTRIB" == "minimal" ]; then
     python -m pip install --upgrade . pytest pytest-cov coverage
 elif [ "$DISTRIB" == "ubuntu" ]; then
-    sudo apt-get install --fix-missing python3-numpy python3-matplotlib python3-pip python3-coverage optipng
+    sudo apt-get install --fix-missing python3-numpy python3-matplotlib python3-pip python3-coverage optipng graphviz
     python3 -m pip install --upgrade pip setuptools
     python3 -m pip install -r dev-requirements.txt | cat
     python3 -m pip install --upgrade pytest pytest-cov coverage

diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -12,3 +12,4 @@ flake8
 check-manifest
 plotly
 absl-py
+graphviz
diff --git a/doc/conf.py b/doc/conf.py
@@ -45,6 +45,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
     'sphinx_gallery.gen_gallery',
+    'sphinx.ext.graphviz',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -397,6 +398,7 @@ def setup(app):
     'matplotlib_animations': True,
     'image_srcset': ["2x"],
     'nested_sections': False,
+    'show_api_usage': True,
 }
 
 # Remove matplotlib agg warnings from generated doc when using plt.show

diff --git a/doc/configuration.rst b/doc/configuration.rst
@@ -58,6 +58,8 @@ file:
 - ``log_level`` (:ref:`log_level`)
 - ``capture_repr`` and ``ignore_repr_types`` (:ref:`capture_repr`)
 - ``nested_sections`` (:ref:`nested_sections`)
+- ``api_usage_ignore`` (:ref:`api_usage_ignore`)
+- ``show_api_usage`` (:ref:`show_api_usage`)
 
 Some options can also be set or overridden on a file-by-file basis:
 
@@ -1861,3 +1863,35 @@ This index file will contain descriptions for the whole gallery as well as for
 each subsection, and a specific toctree for each subsection.
 In particular, sidebars generated using these toctrees might not reflect the
 actual section / folder structure.
+
+.. _show_api_usage:
+
+Showing API Usage
+=================
+
+Optionally, graphs can be made of the usage of each API entry in examples,
+grouped by module. In large projects, there are many modules so this is
+set to ``False`` by default. Setting ``show_api_usage`` to ``True``
+will make one graph per module showing all of the API entries connected to
+the example that they are used in. This could be helpful for making a map
+of which examples to look at if you want to learn about a particular
+module. Note: documentation and graphs of which API examples are unused
+will always be made, only the documentation and graphs of which
+examples each API entry are used in is controlled by this configuration
+parameter. ``graphviz`` is required for making the unused and used API
+entry graphs. See the
+`Sphinx-Gallery API usage documentation and graphs <sg_api_usage.html>`_
+for example. This report can be found in the sphinx output directory under
+``sg_api_usage.html``.
+
+.. _api_usage_ignore:
+
+Ignoring API entries
+====================
+
+By default, ``api_usage_ignore='.*__.*__'`` ignores files that match this
+regular expression in documenting and graphing the usage of API entries
+within the example gallery. This regular expression can be modified to
+ignore any kind of file that should not be considered. The default regular
+expression ignores functions like ``__len__()`` for which it may not be
+desirable to document if they are used in examples.
-Original file line number
+Diff line change
@@ Expand Up / @@ -12,3 +12,4 @@ flake8 @@
     check-manifest
     plotly
     absl-py
+    graphviz