Merge pull request matplotlib#21240 from QuLogic/doc-cleanup

DOC: Fix source links and flake8 cleanup

Author: timhoffm

.flake8

@@ -85,7 +85,7 @@ per-file-ignores =
     lib/mpl_toolkits/tests/conftest.py: F401
     lib/pylab.py: F401, F403
 
-    doc/conf.py: E402, E501
+    doc/conf.py: E402
     tutorials/advanced/path_tutorial.py: E402
     tutorials/advanced/patheffects_guide.py: E402
     tutorials/advanced/transforms_tutorial.py: E402, E501

README.rst

@@ -42,23 +42,24 @@
 
 .. image:: https://matplotlib.org/_static/logo2.svg
 
-Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations in Python.
+Matplotlib is a comprehensive library for creating static, animated, and
+interactive visualizations in Python.
 
 Check out our `home page <https://matplotlib.org/>`_ for more information.
 
 .. image:: https://matplotlib.org/_static/readme_preview.png
 
-Matplotlib produces publication-quality figures in a variety of hardcopy formats
-and interactive environments across platforms. Matplotlib can be used in Python scripts,
-the Python and IPython shell, web application servers, and various
-graphical user interface toolkits.
+Matplotlib produces publication-quality figures in a variety of hardcopy
+formats and interactive environments across platforms. Matplotlib can be used
+in Python scripts, the Python and IPython shell, web application servers, and
+various graphical user interface toolkits.
 
 
 Install
 =======
 
 For installation instructions and requirements, see `INSTALL.rst <INSTALL.rst>`_  or the
-`install <https://matplotlib.org/users/installing.html>`_ documentation.
+`install <https://matplotlib.org/stable/users/installing.html>`_ documentation.
 
 Test
 ====
@@ -67,28 +68,36 @@ After installation, launch the test suite::
 
   python -m pytest
 
-Read the `testing guide <https://matplotlib.org/devel/testing.html>`_ for more information and alternatives.
+Read the `testing guide <https://matplotlib.org/stable/devel/testing.html>`_
+for more information and alternatives.
 
 Contribute
 ==========
+
 You've discovered a bug or something else you want to change - excellent!
 
 You've worked out a way to fix it – even better!
 
 You want to tell us about it – best of all!
 
-Start at the `contributing guide <https://matplotlib.org/devdocs/devel/contributing.html>`_!
+Start at the `contributing guide
+<https://matplotlib.org/devdocs/devel/contributing.html>`_!
 
 Contact
 =======
 
-`Discourse <https://discourse.matplotlib.org/>`_ is the discussion forum for general questions and discussions and our recommended starting point.
+`Discourse <https://discourse.matplotlib.org/>`_ is the discussion forum for
+general questions and discussions and our recommended starting point.
 
 Our active mailing lists (which are mirrored on Discourse) are:
 
-* `Users <https://mail.python.org/mailman/listinfo/matplotlib-users>`_ mailing list: [email protected]
-* `Announcement  <https://mail.python.org/mailman/listinfo/matplotlib-announce>`_ mailing list: [email protected]
-* `Development <https://mail.python.org/mailman/listinfo/matplotlib-devel>`_ mailing list: [email protected]
+* `Users <https://mail.python.org/mailman/listinfo/matplotlib-users>`_ mailing
+  list: [email protected]
+* `Announcement
+  <https://mail.python.org/mailman/listinfo/matplotlib-announce>`_ mailing
+  list: [email protected]
+* `Development <https://mail.python.org/mailman/listinfo/matplotlib-devel>`_
+  mailing list: [email protected]
 
 Gitter_ is for coordinating development and asking questions directly related
 to contributing to matplotlib.
@@ -99,21 +108,21 @@ Citing Matplotlib
 If Matplotlib contributes to a project that leads to publication, please
 acknowledge this by citing Matplotlib.
 
-`A ready-made citation entry <https://matplotlib.org/citing.html>`_ is available.
+`A ready-made citation entry <https://matplotlib.org/stable/citing.html>`_ is
+available.
 
 Research notice
 ~~~~~~~~~~~~~~~
 
 Please note that this repository is participating in a study into
 sustainability of open source projects. Data will be gathered about this
-repository for approximately the next 12 months, starting from June
-2021.
+repository for approximately the next 12 months, starting from June 2021.
 
-Data collected will include number of contributors, number of PRs, time
-taken to close/merge these PRs, and issues closed.
+Data collected will include number of contributors, number of PRs, time taken
+to close/merge these PRs, and issues closed.
 
-For more information, please visit `the informational
-page <https://sustainable-open-science-and-software.github.io/>`__ or
-download the `participant information
-sheet <https://sustainable-open-science-and-software.github.io/assets/PIS_sustainable_software.pdf>`__.
+For more information, please visit `the informational page
+<https://sustainable-open-science-and-software.github.io/>`__ or download the
+`participant information sheet
+<https://sustainable-open-science-and-software.github.io/assets/PIS_sustainable_software.pdf>`__.
 

doc/conf.py

@@ -1,10 +1,12 @@
 # Matplotlib documentation build configuration file, created by
 # sphinx-quickstart on Fri May  2 12:33:25 2008.
 #
-# This file is execfile()d with the current directory set to its containing dir.
+# This file is execfile()d with the current directory set to its containing
+# dir.
 #
 # The contents of this file are pickled, so don't put values in the namespace
-# that aren't pickleable (module imports are okay, they're removed automatically).
+# that aren't pickleable (module imports are okay, they're removed
+# automatically).
 #
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
@@ -30,7 +32,8 @@
 
 # Parse year using SOURCE_DATE_EPOCH, falling back to current time.
 # https://reproducible-builds.org/specs/source-date-epoch/
-sourceyear = datetime.utcfromtimestamp(int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))).year
+sourceyear = datetime.utcfromtimestamp(
+    int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))).year
 
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
@@ -226,9 +229,11 @@ def _check_dependencies():
 }
 
 project = 'Matplotlib'
-copyright = ('2002 - 2012 John Hunter, Darren Dale, Eric Firing, '
-             'Michael Droettboom and the Matplotlib development '
-             f'team; 2012 - {sourceyear} The Matplotlib development team')
+copyright = (
+    '2002 - 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom '
+    'and the Matplotlib development team; '
+    f'2012 - {sourceyear} The Matplotlib development team'
+)
 
 
 # The default replacements for |version| and |release|, also used in various
@@ -389,8 +394,10 @@ def _check_dependencies():
 # The paper size ('letter' or 'a4').
 latex_paper_size = 'letter'
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, document class [howto/manual]).
+# Grouping the document tree into LaTeX files.
+# List of tuples:
+#   (source start file, target name, title, author,
+#    document class [howto/manual])
 
 latex_documents = [
     ('contents', 'Matplotlib.tex', 'Matplotlib',
@@ -575,8 +582,8 @@ def setup(app):
 # You can add build old with link_github = False
 
 if link_github:
-    import re
     import inspect
+    from packaging.version import parse
 
     extensions.append('sphinx.ext.linkcode')
 
@@ -618,23 +625,18 @@ def linkcode_resolve(domain, info):
         except (OSError, TypeError):
             lineno = None
 
-        if lineno:
-            linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1)
-        else:
-            linespec = ""
+        linespec = (f"#L{lineno:d}-L{lineno + len(source) - 1:d}"
+                    if lineno else "")
 
         startdir = Path(matplotlib.__file__).parent.parent
         fn = os.path.relpath(fn, start=startdir).replace(os.path.sep, '/')
 
         if not fn.startswith(('matplotlib/', 'mpl_toolkits/')):
             return None
 
-        m = re.match(r'^.*post[0-9]+\+\w([a-z0-9]+).\w+$', matplotlib.__version__)
-        if m:
-            return "https://github.com/matplotlib/matplotlib/blob/%s/lib/%s%s" % (
-                    m.group(1), fn, linespec)
-        else:
-            return "https://github.com/matplotlib/matplotlib/blob/v%s/lib/%s%s" % (
-                    matplotlib.__version__, fn, linespec)
+        version = parse(matplotlib.__version__)
+        tag = 'master' if version.is_devrelease else f'v{version.base_version}'
+        return ("https://github.com/matplotlib/matplotlib/blob"
+                f"/{tag}/lib/{fn}{linespec}")
 else:
     extensions.append('sphinx.ext.viewcode')

environment.yml

@@ -27,6 +27,7 @@ dependencies:
   - ipython
   - ipywidgets
   - numpydoc>=0.8
+  - packaging
   - pydata-sphinx-theme
   - scipy
   - sphinx>=1.8.1,!=2.0.0

requirements/doc/doc-requirements.txt

@@ -12,6 +12,7 @@ colorspacious
 ipython
 ipywidgets
 numpydoc>=0.8
+packaging>=20
 pydata-sphinx-theme>=0.6.0
 sphinxcontrib-svg2pdfconverter>=1.1.0
 # sphinx-gallery>=0.7