Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 5f5bb21

Browse filesBrowse files
story645story645
committed
contributing->contribute + moving things around + gitter switch
1 parent ca29425 commit 5f5bb21
Copy full SHA for 5f5bb21

File tree

3 files changed

+96
-90
lines changed
Filter options

3 files changed

+96
-90
lines changed

‎doc/devel/contributing.rst renamed to ‎doc/devel/contribute.rst

Copy file name to clipboardExpand all lines: doc/devel/contribute.rst
+24-39Lines changed: 24 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1+
.. redirect-from:: /devel/contributing
2+
13
.. _contributing:
24

3-
============
4-
Contributing
5-
============
5+
==========
6+
Contribute
7+
==========
68

79
You've discovered a bug or something else you want to change
810
in Matplotlib — excellent!
@@ -21,8 +23,8 @@ Matplotlib community.
2123

2224
.. _start-contributing:
2325

24-
Getting started with contributing?
25-
==================================
26+
Get started
27+
===========
2628

2729
There is no pre-defined pathway for new contributors -- we recommend looking at
2830
existing issue and pull request discussions, and following the conversations
@@ -99,11 +101,11 @@ process works, technical questions about the code, what makes for good
99101
documentation or a blog post, how to get involved in community work, or get a
100102
"pre-review" on your PR.
101103

102-
To join, please go to our public gitter_ community channel, and ask to be added
103-
to ``#incubator``. One of our core developers will see your message and
104-
will add you.
104+
To join, please go to our public community_ community channel, and ask
105+
to be added to ``#incubator``. One of our core developers will see your message
106+
and will add you.
105107

106-
New Contributors meeting
108+
New Contributors Meeting
107109
------------------------
108110

109111
Once a month, we host a meeting to discuss topics that interest new
@@ -122,8 +124,8 @@ suggestions. We ❤ feedback!
122124

123125
.. _new_contributors:
124126

125-
Issues for new contributors
126-
---------------------------
127+
Good first issues
128+
-----------------
127129

128130
While any contributions are welcome, we have marked some issues as
129131
particularly suited for new contributors by the label `good first issue
@@ -143,8 +145,8 @@ though not necessarily all at the same time:
143145
- It involves Python features such as decorators and context managers, which
144146
have subtleties due to our implementation decisions.
145147

146-
Assigning issues and duplicating pull requests
147-
----------------------------------------------
148+
Assign issues and duplicate pull requests
149+
-----------------------------------------
148150

149151
In general, the Matplotlib project does not assign issues. Issues are
150152
"assigned" or "claimed" by opening a PR; there is no other assignment
@@ -158,8 +160,8 @@ unresponsive, feel free to open a new PR referencing the old one.
158160

159161
.. _submitting-a-bug-report:
160162

161-
Submitting a bug report
162-
=======================
163+
Submit a bug report
164+
===================
163165

164166
If you find a bug in the code or documentation, do not hesitate to submit a
165167
ticket to the
@@ -196,8 +198,8 @@ Thank you for your help in keeping bug reports complete, targeted and descriptiv
196198

197199
.. _request-a-new-feature:
198200

199-
Requesting a new feature
200-
========================
201+
Request a new feature
202+
=====================
201203

202204
Please post feature requests to the
203205
`Issue Tracker <https://github.com/matplotlib/matplotlib/issues>`_.
@@ -209,8 +211,8 @@ users to then also
209211

210212
.. _contributing-code:
211213

212-
Contributing code
213-
=================
214+
Contribute code
215+
===============
214216

215217
.. _how-to-contribute:
216218

@@ -262,8 +264,8 @@ best practices for contribution, see :ref:`installing_for_devs`.
262264

263265
.. _contributing_documentation:
264266

265-
Contributing documentation
266-
==========================
267+
Contribute documentation
268+
========================
267269

268270
You as an end-user of Matplotlib can make a valuable contribution because you
269271
more clearly see the potential for improvement than a core developer. For example, you can:
@@ -589,22 +591,5 @@ and running the same script will display
589591
my_matplotlib_module.set_range(0, 0) # set range
590592
591593
.. _logging tutorial: https://docs.python.org/3/howto/logging.html#logging-basic-tutorial
592-
593-
.. _sample-data:
594-
595-
Writing examples
596-
----------------
597-
598-
We have hundreds of examples in subdirectories of :file:`matplotlib/examples`,
599-
and these are automatically generated when the website is built to show up in
600-
the :ref:`examples <gallery>` section of the website.
601-
602-
Any sample data that the example uses should be kept small and
603-
distributed with Matplotlib in the
604-
:file:`lib/matplotlib/mpl-data/sample_data/` directory. Then in your
605-
example code you can load it into a file handle with::
606-
607-
import matplotlib.cbook as cbook
608-
fh = cbook.get_sample_data('mydata.dat')
609-
610594
.. _gitter: https://gitter.im/matplotlib/matplotlib
595+
.. _community: https://gitter.im/matplotlib/community

‎doc/devel/documenting_mpl.rst renamed to ‎doc/devel/document.rst

Copy file name to clipboardExpand all lines: doc/devel/document.rst
+59-39Lines changed: 59 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1+
.. redirect-from:: /devel/documenting_mpl
2+
13
.. _documenting-matplotlib:
24

3-
=====================
4-
Writing documentation
5-
=====================
5+
===================
6+
Write documentation
7+
===================
68

79
Getting started
810
===============
@@ -39,8 +41,8 @@ contents of :file:`index.rst` of the subdirectory. See
3941
(excepting :file:`doc/api/api_changes/`). Sphinx_ regenerates
4042
files in these directories when building documentation.
4143

42-
Setting up the doc build
43-
------------------------
44+
Set up the build
45+
----------------
4446

4547
The documentation for Matplotlib is generated from reStructuredText (ReST_)
4648
using the Sphinx_ documentation generation tool.
@@ -50,8 +52,8 @@ To build the documentation you will need to
5052
particular the :ref:`additional dependencies <doc-dependencies>` required to
5153
build the documentation.
5254

53-
Building the docs
54-
-----------------
55+
Build the docs
56+
--------------
5557

5658
The documentation sources are found in the :file:`doc/` directory.
5759
The configuration file for Sphinx is :file:`doc/conf.py`. It controls which
@@ -105,8 +107,8 @@ On Windows, set the options as environment variables, e.g.:
105107
106108
set SPHINXOPTS= & set O=-j4 -Dplot_formats=png:100 & make html
107109
108-
Showing locally built docs
109-
--------------------------
110+
Show locally built docs
111+
-----------------------
110112

111113
The built docs are available in the folder :file:`build/html`. A shortcut
112114
for opening them in your default browser is:
@@ -117,8 +119,8 @@ for opening them in your default browser is:
117119
118120
.. _writing-rest-pages:
119121

120-
Writing ReST pages
121-
==================
122+
Write ReST pages
123+
================
122124

123125
Most documentation is either in the docstrings of individual
124126
classes and methods, in explicit ``.rst`` files, or in examples and tutorials.
@@ -189,8 +191,8 @@ nor the ````literal```` role:
189191
190192
.. _internal-section-refs:
191193

192-
Referring to other documents and sections
193-
-----------------------------------------
194+
Refer to other documents and sections
195+
-------------------------------------
194196

195197
Sphinx_ allows internal references_ between documents.
196198

@@ -254,8 +256,8 @@ hyphens to separate words.
254256

255257
.. _referring-to-other-code:
256258

257-
Referring to other code
258-
-----------------------
259+
Refer to other code
260+
-------------------
259261

260262
To link to other methods, classes, or modules in Matplotlib you can use
261263
back ticks, for example:
@@ -313,8 +315,8 @@ commands::
313315

314316
.. _rst-figures-and-includes:
315317

316-
Including figures and files
317-
---------------------------
318+
Include figures and files
319+
-------------------------
318320

319321
Image files can directly included in pages with the ``image::`` directive.
320322
e.g., :file:`tutorials/intermediate/constrainedlayout_guide.py` displays
@@ -353,8 +355,8 @@ expression in the Matplotlib figure. In these cases, you can use the
353355

354356
.. _writing-docstrings:
355357

356-
Writing docstrings
357-
==================
358+
Write docstrings
359+
================
358360

359361
Most of the API documentation is written in docstrings. These are comment
360362
blocks in source code that explain how the code works.
@@ -516,8 +518,8 @@ Non-numeric homogeneous sequences are described as lists, e.g.::
516518
list of str
517519
list of `.Artist`
518520

519-
Referencing types
520-
~~~~~~~~~~~~~~~~~
521+
Reference types
522+
~~~~~~~~~~~~~~~
521523
Generally, the rules from referring-to-other-code_ apply. More specifically:
522524

523525
Use full references ```~matplotlib.colors.Normalize``` with an
@@ -584,8 +586,8 @@ also`` sections. No need to use backticks there::
584586
vlines : vertical lines
585587
axhline : horizontal line across the Axes
586588

587-
Wrapping parameter lists
588-
~~~~~~~~~~~~~~~~~~~~~~~~
589+
Wrap parameter lists
590+
~~~~~~~~~~~~~~~~~~~~
589591
Long parameter lists should be wrapped using a ``\`` for continuation and
590592
starting on the new line without any indent (no indent because pydoc will
591593
parse the docstring and strip the line continuation so that indent would
@@ -744,8 +746,8 @@ point, `.kwdoc` can list the properties and interpolate them into
744746
``__init__.__doc__``.
745747

746748

747-
Inheriting docstrings
748-
---------------------
749+
Inherit docstrings
750+
------------------
749751

750752
If a subclass overrides a method but does not change the semantics, we can
751753
reuse the parent docstring for the method of the child class. Python does this
@@ -768,8 +770,8 @@ the future::
768770

769771
.. _docstring-adding-figures:
770772

771-
Adding figures
772-
--------------
773+
Add figures
774+
-----------
773775

774776
As above (see :ref:`rst-figures-and-includes`), figures in the examples gallery
775777
can be referenced with a ``.. plot::`` directive pointing to the python script
@@ -813,8 +815,8 @@ code will also appear in interactive docstrings.
813815

814816
.. _writing-examples-and-tutorials:
815817

816-
Writing examples and tutorials
817-
==============================
818+
Write examples and tutorials
819+
============================
818820

819821
Examples and tutorials are Python scripts that are run by `Sphinx Gallery`_.
820822
Sphinx Gallery finds ``*.py`` files in source directories and runs the files to
@@ -841,8 +843,8 @@ these ``*.rst`` files from the source location to the build location (see
841843
In the Python files, to exclude an example from having a plot generated, insert
842844
"sgskip" somewhere in the filename.
843845

844-
Formatting the example
845-
----------------------
846+
Format
847+
------
846848

847849
The format of these files is relatively straightforward. Properly
848850
formatted comment blocks are treated as ReST_ text, the code is
@@ -913,8 +915,25 @@ ReST text are delimited by the line ``# %%`` :
913915
914916
In this way text, code, and figures are output in a "notebook" style.
915917

916-
References for sphinx-gallery
917-
-----------------------------
918+
.. _sample-data:
919+
920+
Data
921+
----
922+
923+
The data should be written out in the code. If the data is too
924+
large for this to be feasible, it can instead be loaded using ~cbook.sample_data
925+
926+
.. code-block:: python
927+
928+
import matplotlib.cbook as cbook
929+
fh = cbook.get_sample_data('mydata.dat')
930+
931+
932+
If data cannot be included in the code, it should be added to
933+
:file:`lib/matplotlib/mpl-data/sample_data/`
934+
935+
Create mini-gallery
936+
-------------------
918937

919938
The showcased Matplotlib functions should be listed in an admonition at the
920939
bottom as follows
@@ -942,8 +961,9 @@ Functions that exist in ``pyplot`` as well as in Axes or Figure should mention
942961
both references no matter which one is used in the example code. The ``pyplot``
943962
reference should always be the second to mention; see the example above.
944963

945-
Order of examples in the gallery
946-
--------------------------------
964+
965+
Order examples
966+
--------------
947967

948968
The order of the sections of the :ref:`tutorials` and the :ref:`gallery`, as
949969
well as the order of the examples within each section are determined in a
@@ -984,8 +1004,8 @@ manual ``index.rst``.
9841004
Miscellaneous
9851005
=============
9861006

987-
Moving documentation
988-
--------------------
1007+
Move documentation
1008+
------------------
9891009

9901010
Sometimes it is desirable to move or consolidate documentation. With no
9911011
action this will lead to links either going dead (404) or pointing to old
@@ -1020,8 +1040,8 @@ For clarity, do not use relative links.
10201040

10211041
.. _inheritance-diagrams:
10221042

1023-
Generating inheritance diagrams
1024-
-------------------------------
1043+
Generate inheritance diagrams
1044+
-----------------------------
10251045

10261046
Class inheritance diagrams can be generated with the Sphinx
10271047
`inheritance-diagram`_ directive.

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.