Merge branch 'v3.2.0-doc' into v3.2.x

QuLogic · QuLogic · commit 56666b851add · 2020-03-17T17:13:34.000-04:00
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -1,7 +1,7 @@
 # Circle CI configuration file
 # https://circleci.com/docs/
 
-version: 2
+version: 2.1
 
 
 ###########################################
@@ -115,10 +115,6 @@ jobs:
       - store_artifacts:
           path: doc/build/html
 
-      - run:
-          name: "Built documentation is available at:"
-          command: echo "${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/doc/build/html/index.html"
-
   docs-python37:
     docker:
       - image: circleci/python:3.7
@@ -141,9 +137,6 @@ jobs:
       - store_artifacts:
           path: doc/build/html
 
-      - run:
-          name: "Built documentation is available at:"
-          command: echo "${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/doc/build/html/index.html"
 
       - add_ssh_keys:
           fingerprints:
diff --git a/.github/workflows/circleci.yml b/.github/workflows/circleci.yml
@@ -0,0 +1,12 @@
+on: [status]
+jobs:
+  circleci_artifacts_redirector_job:
+    runs-on: ubuntu-latest
+    name: Run CircleCI artifacts redirector
+    steps:
+      - name: GitHub Action step
+        uses: larsoner/circleci-artifacts-redirector-action@master
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          artifact-path: 0/doc/build/html/index.html
+          circleci-jobs: docs-python36,docs-python37
diff --git a/doc/_templates/sidebar_announcement.html b/doc/_templates/sidebar_announcement.html
@@ -1,5 +1,5 @@
 <div class="sidebar-announcement">
   <p>Matplotlib 3.0 is Python 3 only.</p>
-  <p>For Python 2 support, Matplotlib 2.2.x will be continued as a LTS release
-      and updated with bugfixes until January 1, 2020.</p>
+  <p>Python 2 support has been dropped on January 1, 2020.</p>
+  <p>The last Python 2 compatible release is 2.2.5.</p>
 </div>
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -174,6 +174,8 @@ environment is set up properly::
 Contributing code
 =================
 
+.. _how-to-contribute:
+
 How to contribute
 -----------------
 
@@ -222,7 +224,7 @@ want to consider sending an email to the mailing list for more visibility.
   * `Git documentation <https://git-scm.com/documentation>`_
   * `Git-Contributing to a Project <https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project>`_
   * `Introduction to GitHub  <https://lab.github.com/githubtraining/introduction-to-github>`_
-  * :ref:`development-workflow`.
+  * :ref:`development-workflow`
   * :ref:`using-git`
 
 Contributing pull requests
@@ -316,21 +318,35 @@ This helps the contributor become familiar with the contribution
 workflow, and for the core devs to become acquainted with the contributor;
 besides which, we frequently underestimate how easy an issue is to solve!
 
-.. _other_ways_to_contribute:
 
-Other ways to contribute
-=========================
+.. _contributing_documentation:
 
+Contributing documentation
+==========================
 
 Code is not the only way to contribute to Matplotlib. For instance,
 documentation is also a very important part of the project and often doesn't
 get as much attention as it deserves. If you find a typo in the documentation,
 or have made improvements, do not hesitate to send an email to the mailing
-list or submit a GitHub pull request. Full documentation can be found under
-the doc/ directory.
+list or submit a GitHub pull request.  To make a pull request, refer to the
+guidelines outlined in :ref:`how-to-contribute`.
+
+Full documentation can be found under the :file:`doc/`, :file:`tutorials/`,
+and :file:`examples/` directories.
+
+.. seealso::
+  * :ref:`documenting-matplotlib`
+
+
+.. _other_ways_to_contribute:
+
+Other ways to contribute
+=========================
 
 It also helps us if you spread the word: reference the project from your blog
-and articles or link to it from your website!
+and articles or link to it from your website!  If Matplotlib contributes to a
+project that leads to a scientific publication, please follow the
+:doc:`/citing` guidelines.
 
 .. _coding_guidelines:
 
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -18,45 +18,67 @@ Getting started
 General file structure
 ----------------------
 
-All documentation is built from the :file:`doc/` directory.  This directory
-contains both reStructuredText (ReST_; ``.rst``) files that contain pages in
-the documentation and configuration files for Sphinx_.
+All documentation is built from the :file:`doc/`, :file:`tutorials/`, and
+:file:`examples/` directories.  The :file:`doc/` directory contains configuration files for Sphinx
+and  reStructuredText (ReST_; ``.rst``) files that are rendered to documentation pages. 
 
-The ``.rst`` files are kept in :file:`doc/users`,
-:file:`doc/devel`, :file:`doc/api` and :file:`doc/faq`. The main entry point is
-:file:`doc/index.rst`, which pulls in the :file:`index.rst` file for the users
-guide, developers guide, api reference, and FAQs. The documentation suite is
-built as a single document in order to make the most effective use of cross
-referencing.
+
+The main entry point is :file:`doc/index.rst`, which pulls in the
+:file:`index.rst` file for the users guide (:file:`doc/users`), developers
+guide (:file:`doc/devel`), api reference (:file:`doc/api`), and FAQs
+(:file:`doc/faq`). The documentation suite is built as a single document in
+order to make the most effective use of cross referencing.
 
 Sphinx_ also creates ``.rst`` files that are staged in :file:`doc/api` from
 the docstrings of the classes in the Matplotlib library.  Except for
 :file:`doc/api/api_changes/`, these ``.rst`` files are created when the
 documentation is built.
 
 Similarly, the contents of :file:`doc/gallery` and :file:`doc/tutorials` are
-generated by the `Sphinx Gallery`_ from the sources in :file:`examples` and
-:file:`tutorials`.  These sources consist of python scripts that have ReST_
-documentation built into their comments.  Don't directly edit the
-``.rst`` files in :file:`doc/gallery` and :file:`doc/tutorials` as they are
-regenerated when the documentation are built.
+generated by the `Sphinx Gallery`_ from the sources in :file:`examples/` and
+:file:`tutorials/`.  These sources consist of python scripts that have ReST_
+documentation built into their comments.
+
+.. note::
+
+  Don't directly edit the ``.rst`` files in :file:`doc/gallery`, 
+  :file:`doc/tutorials`, and :file:`doc/api` (excepting
+  :file:`doc/api/api_changes/`).  Sphinx_ regenerates files in these
+  directories when building documentation.
 
 Installing dependencies
 -----------------------
 
 The documentation for Matplotlib is generated from reStructuredText (ReST_)
-using the Sphinx_ documentation generation tool. There are several extra
-requirements that are needed to build the documentation. They are listed in
-:file:`doc-requirements.txt`, which is shown below:
+using the Sphinx_ documentation generation tool. To build the documentation
+you will need to (1) set up an appropriate Python environment and (2)
+separately install LaTeX and Graphviz.
+
+To (1) set up an appropriate Python environment for building the
+documentation, you should:
+
+*  create a clean virtual environment with no existing Matplotlib
+   installation
+*  install the Python packages required for Matplotlib
+*  install the additional Python packages required to build the documentation
+
+There are several extra python packages that are needed to build the
+documentation. They are listed in :file:`doc-requirements.txt`, which is
+shown below:
 
 .. include:: ../../requirements/doc/doc-requirements.txt
    :literal:
 
+To (2) set up LaTeX and Graphviz dependencies you should:
+
+*  install a minimal working LaTeX distribution
+*  install the LaTeX packages cm-super and dvipng
+*  install `Graphviz <http://www.graphviz.org/download>`_
+
 .. note::
 
-  * You'll need a minimal working LaTeX distribution for many examples to run.
-  * `Graphviz <http://www.graphviz.org/Download.php>`_ is not a Python package,
-    and needs to be installed separately.
+  The documentation will not build without LaTeX and Graphviz.  These are not
+  Python packages and must be installed separately.
 
 Building the docs
 -----------------
diff --git a/examples/scales/log_bar.py b/examples/scales/log_bar.py
@@ -20,7 +20,8 @@
     y = [d[i] for d in data]
     b = ax.bar(x + i * dimw, y, dimw, bottom=0.001)
 
-ax.set_xticks(x + dimw / 2, map(str, x))
+ax.set_xticks(x + dimw / 2)
+ax.set_xticklabels(map(str, x))
 ax.set_yscale('log')
 
 ax.set_xlabel('x')
diff --git a/examples/text_labels_and_annotations/text_rotation.py b/examples/text_labels_and_annotations/text_rotation.py
@@ -30,21 +30,20 @@ def addtext(ax, props):
     for x in range(0, 5):
         ax.scatter(x + 0.5, 0.5, color='r', alpha=0.5)
     ax.set_yticks([0, .5, 1])
+    ax.set_xticks(np.arange(0, 5.1, 0.5))
     ax.set_xlim(0, 5)
     ax.grid(True)
 
 
 # the text bounding box
 bbox = {'fc': '0.8', 'pad': 0}
 
-fig, axs = plt.subplots(2, 1)
+fig, axs = plt.subplots(2, 1, sharex=True)
 
 addtext(axs[0], {'ha': 'center', 'va': 'center', 'bbox': bbox})
-axs[0].set_xticks(np.arange(0, 5.1, 0.5), [])
 axs[0].set_ylabel('center / center')
 
 addtext(axs[1], {'ha': 'left', 'va': 'bottom', 'bbox': bbox})
-axs[1].set_xticks(np.arange(0, 5.1, 0.5))
 axs[1].set_ylabel('left / bottom')
 
 plt.show()
diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -1165,9 +1165,6 @@ def set_linestyle(self, ls):
               ``'None'`` or ``' '`` or ``''``   draw nothing
               ===============================   =================
 
-              Optionally, the string may be preceded by a drawstyle, e.g.
-              ``'steps--'``. See :meth:`set_drawstyle` for details.
-
             - Alternatively a dash tuple of the following form can be
               provided::
 
diff --git a/tutorials/colors/colormaps.py b/tutorials/colors/colormaps.py
@@ -225,7 +225,7 @@ def plot_color_gradients(cmap_category, cmap_list, nrows):
 plt.show()
 
 ###############################################################################
-# Lightness of matplotlib colormaps
+# Lightness of Matplotlib colormaps
 # =================================
 #
 # Here we examine the lightness values of the matplotlib colormaps.
@@ -308,10 +308,9 @@ def plot_color_gradients(cmap_category, cmap_list, nrows):
         formatter = mpl.ticker.FixedFormatter(cmap_list[i*dsub:(i+1)*dsub])
         ax.xaxis.set_major_formatter(formatter)
         ax.xaxis.set_tick_params(rotation=50)
+        ax.set_ylabel('Lightness $L^*$', fontsize=12)
 
     ax.set_xlabel(cmap_category + ' colormaps', fontsize=14)
-    fig.text(0.0, 0.55, 'Lightness $L^*$', fontsize=12,
-             transform=fig.transFigure, rotation=90)
 
     fig.tight_layout(h_pad=0.0, pad=1.5)
     plt.show()
