Merge pull request #21461 from jklymak/backport-21429

timhoffm · web-flow · commit 13a439b7b7cc · 2021-10-26T22:45:31.000+02:00
Backport #21429 from jklymak/doc-use-mpl-sphinx
diff --git a/doc/_templates/mpl_nav_bar.html b/doc/_templates/mpl_nav_bar.html
diff --git a/doc/conf.py b/doc/conf.py
@@ -292,7 +292,7 @@ def _check_dependencies():
     f"mpl.css?{SHA}",
 ]
 
-html_theme = "pydata_sphinx_theme"
+html_theme = "mpl_sphinx_theme"
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -302,34 +302,12 @@ def _check_dependencies():
 # the sidebar.
 html_logo = "_static/logo2.svg"
 html_theme_options = {
+    "native_site": True,
     "logo_link": "index",
     # 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",
-            "url": "https://gitter.im/matplotlib",
-            "icon": "fab fa-gitter",
-        },
-        {
-            "name": "discourse",
-            "url": "https://discourse.matplotlib.org",
-            "icon": "fab fa-discourse",
-        },
-        {
-            "name": "GitHub",
-            "url": "https://github.com/matplotlib/matplotlib",
-            "icon": "fab fa-github-square",
-        },
-        {
-            "name": "twitter",
-            "url": "https://twitter.com/matplotlib/",
-            "icon": "fab fa-twitter-square",
-        },
-    ],
     "show_prev_next": False,
-    "navbar_center": ["mpl_nav_bar.html"],
 }
 include_analytics = is_release_build
 if include_analytics:
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -1019,6 +1019,14 @@ Example:
    :parts: 2
 
 
+Navbar and style
+----------------
+
+Matplotlib has a few subprojects that share the same navbar and style, so these 
+are centralized as a sphinx theme at
+`mpl_sphinx_theme <https://github.com/matplotlib/mpl-sphinx-theme>`_.  Changes to the 
+style or topbar should be made there to propagate across all subprojects.  
+
 .. TODO: Add section about uploading docs
 
 .. _ReST: https://docutils.sourceforge.io/rst.html
diff --git a/environment.yml b/environment.yml
@@ -0,0 +1,58 @@
+# To set up a development environment using conda run:
+#
+#   conda env create -f environment.yml
+#   conda activate mpl-dev
+#   pip install -e .
+#
+name: mpl-dev
+channels:
+  - conda-forge
+dependencies:
+  - cairocffi
+  - cycler>=0.10.0
+  - fonttools>=4.22.0
+  - kiwisolver>=1.0.1
+  - numpy>=1.17
+  - pillow>=6.2
+  - pygobject
+  - pyparsing
+  - pyqt
+  - python-dateutil>=2.1
+  - setuptools
+  - setuptools_scm
+  - wxpython
+  # building documentation
+  - colorspacious
+  - graphviz
+  - ipython
+  - ipywidgets
+  - numpydoc>=0.8
+  - packaging
+  - pydata-sphinx-theme
+  - scipy
+  - sphinx>=1.8.1,!=2.0.0
+  - sphinx-copybutton
+  - sphinx-gallery>=0.10
+  - sphinx-panels
+  - pip
+  - pip:
+      - mpl-sphinx-theme
+      - sphinxcontrib-svg2pdfconverter
+  # testing
+  - coverage
+  - flake8>=3.8
+  - flake8-docstrings>=1.4.0
+  - gtk3
+  - ipykernel
+  - nbconvert[execute]!=6.0.0,!=6.0.1
+  - nbformat!=5.0.0,!=5.0.1
+  - pandas!=0.25.0
+  - pikepdf
+  - pydocstyle>=5.1.0
+  - pytest!=4.6.0,!=5.4.0
+  - pytest-cov
+  - pytest-rerunfailures
+  - pytest-timeout
+  - pytest-xdist
+  - tornado
+  - pytz
diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt
@@ -13,7 +13,7 @@ ipython
 ipywidgets
 numpydoc>=0.8
 packaging>=20
-pydata-sphinx-theme>=0.6.0
+mpl-sphinx-theme
 sphinxcontrib-svg2pdfconverter>=1.1.0
 sphinx-gallery>=0.10
 sphinx-copybutton
