From d3b46f2939b54e67aeaa9658ba991afde9bc6c8d Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Mon, 27 Sep 2021 22:34:37 -0400 Subject: [PATCH 1/3] Clean up doc configuration slightly --- .flake8 | 2 +- doc/conf.py | 41 ++++++++++++++++++++++------------------- 2 files changed, 23 insertions(+), 20 deletions(-) diff --git a/.flake8 b/.flake8 index 7094b6c49b5f..9de6a96bfc59 100644 --- a/.flake8 +++ b/.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 diff --git a/doc/conf.py b/doc/conf.py index 7774b0f726eb..a48039524b6b 100644 --- a/doc/conf.py +++ b/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', @@ -618,10 +625,8 @@ 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, '/') @@ -629,12 +634,10 @@ def linkcode_resolve(domain, info): 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) + m = re.match(r'^.*post[0-9]+\+\w([a-z0-9]+).\w+$', + matplotlib.__version__) + version = m.group(1) if m else f'v{matplotlib.__version__}' + return ("https://github.com/matplotlib/matplotlib/blob" + f"/{version}/lib/{fn}{linespec}") else: extensions.append('sphinx.ext.viewcode') From d1a4a11583fa1e26a2572cd5a0264c5964823fde Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Mon, 27 Sep 2021 22:39:40 -0400 Subject: [PATCH 2/3] Re-wrap toplevel readme --- README.rst | 51 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 21 deletions(-) diff --git a/README.rst b/README.rst index f6695c964068..078898049a55 100644 --- a/README.rst +++ b/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 `_ 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 `_ or the -`install `_ documentation. +`install `_ documentation. Test ==== @@ -67,28 +68,36 @@ After installation, launch the test suite:: python -m pytest -Read the `testing guide `_ for more information and alternatives. +Read the `testing guide `_ +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 `_! +Start at the `contributing guide +`_! Contact ======= -`Discourse `_ is the discussion forum for general questions and discussions and our recommended starting point. +`Discourse `_ 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 `_ mailing list: matplotlib-users@python.org -* `Announcement `_ mailing list: matplotlib-announce@python.org -* `Development `_ mailing list: matplotlib-devel@python.org +* `Users `_ mailing + list: matplotlib-users@python.org +* `Announcement + `_ mailing + list: matplotlib-announce@python.org +* `Development `_ + mailing list: matplotlib-devel@python.org 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 `_ is available. +`A ready-made citation entry `_ 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 `__ or -download the `participant information -sheet `__. +For more information, please visit `the informational page +`__ or download the +`participant information sheet +`__. From 96fa1950e7a70387d53712490fe95a8215accc1c Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Thu, 30 Sep 2021 19:11:12 -0400 Subject: [PATCH 3/3] Fix links to doc sources Instead of figuring out a regex ourselves, just use `packaging` to determine the version. And point to `master` branch if not on an actual tag. Fixes #21230 --- doc/conf.py | 9 ++++----- environment.yml | 1 + requirements/doc/doc-requirements.txt | 1 + 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index a48039524b6b..e703fc724e06 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -582,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') @@ -634,10 +634,9 @@ def linkcode_resolve(domain, info): if not fn.startswith(('matplotlib/', 'mpl_toolkits/')): return None - m = re.match(r'^.*post[0-9]+\+\w([a-z0-9]+).\w+$', - matplotlib.__version__) - version = m.group(1) if m else f'v{matplotlib.__version__}' + version = parse(matplotlib.__version__) + tag = 'master' if version.is_devrelease else f'v{version.base_version}' return ("https://github.com/matplotlib/matplotlib/blob" - f"/{version}/lib/{fn}{linespec}") + f"/{tag}/lib/{fn}{linespec}") else: extensions.append('sphinx.ext.viewcode') diff --git a/environment.yml b/environment.yml index eb284c6ab09d..1f9ad4471d2c 100644 --- a/environment.yml +++ b/environment.yml @@ -27,6 +27,7 @@ dependencies: - ipython - ipywidgets - numpydoc>=0.8 + - packaging - pydata-sphinx-theme - scipy - sphinx>=1.8.1,!=2.0.0 diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt index 8be10d4d107c..8e7172966a4e 100644 --- a/requirements/doc/doc-requirements.txt +++ b/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