Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 9aaca29

Browse files
tacaswelltacaswell
authored
Merge pull request #16813 from QuLogic/v3.2.x
DOC: Prep for 3.2.1
2 parents 4897c4d + 13e21ad commit 9aaca29

File tree

13 files changed

+1323
-1183
lines changed

13 files changed

+1323
-1183
lines changed

‎.circleci/config.yml

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Circle CI configuration file
22
# https://circleci.com/docs/
33

4-
version: 2
4+
version: 2.1
55

66

77
###########################################
@@ -115,10 +115,6 @@ jobs:
115115
- store_artifacts:
116116
path: doc/build/html
117117

118-
- run:
119-
name: "Built documentation is available at:"
120-
command: echo "${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/doc/build/html/index.html"
121-
122118
docs-python37:
123119
docker:
124120
- image: circleci/python:3.7
@@ -141,9 +137,6 @@ jobs:
141137
- store_artifacts:
142138
path: doc/build/html
143139

144-
- run:
145-
name: "Built documentation is available at:"
146-
command: echo "${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/doc/build/html/index.html"
147140

148141
- add_ssh_keys:
149142
fingerprints:

‎.github/workflows/circleci.yml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
on: [status]
2+
jobs:
3+
circleci_artifacts_redirector_job:
4+
runs-on: ubuntu-latest
5+
name: Run CircleCI artifacts redirector
6+
steps:
7+
- name: GitHub Action step
8+
uses: larsoner/circleci-artifacts-redirector-action@master
9+
with:
10+
repo-token: ${{ secrets.GITHUB_TOKEN }}
11+
artifact-path: 0/doc/build/html/index.html
12+
circleci-jobs: docs-python36,docs-python37

‎doc/_templates/sidebar_announcement.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<div class="sidebar-announcement">
22
<p>Matplotlib 3.0 is Python 3 only.</p>
3-
<p>For Python 2 support, Matplotlib 2.2.x will be continued as a LTS release
4-
and updated with bugfixes until January 1, 2020.</p>
3+
<p>Python 2 support has been dropped on January 1, 2020.</p>
4+
<p>The last Python 2 compatible release is 2.2.5.</p>
55
</div>

‎doc/devel/contributing.rst

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,8 @@ environment is set up properly::
174174
Contributing code
175175
=================
176176

177+
.. _how-to-contribute:
178+
177179
How to contribute
178180
-----------------
179181

@@ -222,7 +224,7 @@ want to consider sending an email to the mailing list for more visibility.
222224
* `Git documentation <https://git-scm.com/documentation>`_
223225
* `Git-Contributing to a Project <https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project>`_
224226
* `Introduction to GitHub <https://lab.github.com/githubtraining/introduction-to-github>`_
225-
* :ref:`development-workflow`.
227+
* :ref:`development-workflow`
226228
* :ref:`using-git`
227229

228230
Contributing pull requests
@@ -316,21 +318,35 @@ This helps the contributor become familiar with the contribution
316318
workflow, and for the core devs to become acquainted with the contributor;
317319
besides which, we frequently underestimate how easy an issue is to solve!
318320

319-
.. _other_ways_to_contribute:
320321

321-
Other ways to contribute
322-
=========================
322+
.. _contributing_documentation:
323323

324+
Contributing documentation
325+
==========================
324326

325327
Code is not the only way to contribute to Matplotlib. For instance,
326328
documentation is also a very important part of the project and often doesn't
327329
get as much attention as it deserves. If you find a typo in the documentation,
328330
or have made improvements, do not hesitate to send an email to the mailing
329-
list or submit a GitHub pull request. Full documentation can be found under
330-
the doc/ directory.
331+
list or submit a GitHub pull request. To make a pull request, refer to the
332+
guidelines outlined in :ref:`how-to-contribute`.
333+
334+
Full documentation can be found under the :file:`doc/`, :file:`tutorials/`,
335+
and :file:`examples/` directories.
336+
337+
.. seealso::
338+
* :ref:`documenting-matplotlib`
339+
340+
341+
.. _other_ways_to_contribute:
342+
343+
Other ways to contribute
344+
=========================
331345

332346
It also helps us if you spread the word: reference the project from your blog
333-
and articles or link to it from your website!
347+
and articles or link to it from your website! If Matplotlib contributes to a
348+
project that leads to a scientific publication, please follow the
349+
:doc:`/citing` guidelines.
334350

335351
.. _coding_guidelines:
336352

‎doc/devel/documenting_mpl.rst

Lines changed: 43 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -18,45 +18,68 @@ Getting started
1818
General file structure
1919
----------------------
2020

21-
All documentation is built from the :file:`doc/` directory. This directory
22-
contains both reStructuredText (ReST_; ``.rst``) files that contain pages in
23-
the documentation and configuration files for Sphinx_.
21+
All documentation is built from the :file:`doc/`, :file:`tutorials/`, and
22+
:file:`examples/` directories. The :file:`doc/` directory contains
23+
configuration files for Sphinx and reStructuredText (ReST_; ``.rst``) files
24+
that are rendered to documentation pages.
2425

25-
The ``.rst`` files are kept in :file:`doc/users`,
26-
:file:`doc/devel`, :file:`doc/api` and :file:`doc/faq`. The main entry point is
27-
:file:`doc/index.rst`, which pulls in the :file:`index.rst` file for the users
28-
guide, developers guide, api reference, and FAQs. The documentation suite is
29-
built as a single document in order to make the most effective use of cross
30-
referencing.
26+
27+
The main entry point is :file:`doc/index.rst`, which pulls in the
28+
:file:`index.rst` file for the users guide (:file:`doc/users`), developers
29+
guide (:file:`doc/devel`), api reference (:file:`doc/api`), and FAQs
30+
(:file:`doc/faq`). The documentation suite is built as a single document in
31+
order to make the most effective use of cross referencing.
3132

3233
Sphinx_ also creates ``.rst`` files that are staged in :file:`doc/api` from
3334
the docstrings of the classes in the Matplotlib library. Except for
3435
:file:`doc/api/api_changes/`, these ``.rst`` files are created when the
3536
documentation is built.
3637

3738
Similarly, the contents of :file:`doc/gallery` and :file:`doc/tutorials` are
38-
generated by the `Sphinx Gallery`_ from the sources in :file:`examples` and
39-
:file:`tutorials`. These sources consist of python scripts that have ReST_
40-
documentation built into their comments. Don't directly edit the
41-
``.rst`` files in :file:`doc/gallery` and :file:`doc/tutorials` as they are
42-
regenerated when the documentation are built.
39+
generated by the `Sphinx Gallery`_ from the sources in :file:`examples/` and
40+
:file:`tutorials/`. These sources consist of python scripts that have ReST_
41+
documentation built into their comments.
42+
43+
.. note::
44+
45+
Don't directly edit the ``.rst`` files in :file:`doc/gallery`,
46+
:file:`doc/tutorials`, and :file:`doc/api` (excepting
47+
:file:`doc/api/api_changes/`). Sphinx_ regenerates files in these
48+
directories when building documentation.
4349

4450
Installing dependencies
4551
-----------------------
4652

4753
The documentation for Matplotlib is generated from reStructuredText (ReST_)
48-
using the Sphinx_ documentation generation tool. There are several extra
49-
requirements that are needed to build the documentation. They are listed in
50-
:file:`doc-requirements.txt`, which is shown below:
54+
using the Sphinx_ documentation generation tool. To build the documentation
55+
you will need to (1) set up an appropriate Python environment and (2)
56+
separately install LaTeX and Graphviz.
57+
58+
To (1) set up an appropriate Python environment for building the
59+
documentation, you should:
60+
61+
* create a clean virtual environment with no existing Matplotlib
62+
installation
63+
* install the Python packages required for Matplotlib
64+
* install the additional Python packages required to build the documentation
65+
66+
There are several extra python packages that are needed to build the
67+
documentation. They are listed in :file:`doc-requirements.txt`, which is
68+
shown below:
5169

5270
.. include:: ../../requirements/doc/doc-requirements.txt
5371
:literal:
5472

73+
To (2) set up LaTeX and Graphviz dependencies you should:
74+
75+
* install a minimal working LaTeX distribution
76+
* install the LaTeX packages cm-super and dvipng
77+
* install `Graphviz <http://www.graphviz.org/download>`_
78+
5579
.. note::
5680

57-
* You'll need a minimal working LaTeX distribution for many examples to run.
58-
* `Graphviz <http://www.graphviz.org/Download.php>`_ is not a Python package,
59-
and needs to be installed separately.
81+
The documentation will not build without LaTeX and Graphviz. These are not
82+
Python packages and must be installed separately.
6083

6184
Building the docs
6285
-----------------

‎doc/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -198,7 +198,7 @@ Open source
198198
Matplotlib is a Sponsored Project of NumFOCUS, a 501(c)(3) nonprofit
199199
charity in the United States. NumFOCUS provides Matplotlib with
200200
fiscal, legal, and administrative support to help ensure the health
201-
and sustainability of the project. Visit `numfocus.org <nf>`_ for more
201+
and sustainability of the project. Visit `numfocus.org <nf_>`_ for more
202202
information.
203203

204204
Donations to Matplotlib are managed by NumFOCUS. For donors in the

0 commit comments

Comments
 (0)