Skip to content

DOC: contributing and documenting clean ups + community for incubator invites #25913

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 20, 2023
Merged

DOC: contributing and documenting clean ups + community for incubator invites #25913

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 24 additions & 39 deletions doc/devel/contributing.rst → doc/devel/contribute.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
.. redirect-from:: /devel/contributing

.. _contributing:

============
Contributing
============
==========
Contribute
==========

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

.. _start-contributing:

Getting started with contributing?
==================================
Get started
===========

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

To join, please go to our public community_ channel, and ask to be added
to ``#incubator``. One of our core developers will see your message and
will add you.
To join, please go to our public community_ channel, and ask
to be added to ``#incubator``. One of our core developers will see your message
and will add you.

New Contributors meeting
New Contributors Meeting
------------------------

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

.. _new_contributors:

Issues for new contributors
---------------------------
Good first issues
-----------------

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

Assigning issues and duplicating pull requests
----------------------------------------------

Work on an issue
----------------

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

.. _submitting-a-bug-report:

Submitting a bug report
=======================
Submit a bug report
===================

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

.. _request-a-new-feature:

Requesting a new feature
========================
Request a new feature
=====================

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

.. _contributing-code:

Contributing code
=================
Contribute code
===============

.. _how-to-contribute:

Expand Down Expand Up @@ -262,8 +265,8 @@ best practices for contribution, see :ref:`installing_for_devs`.

.. _contributing_documentation:

Contributing documentation
==========================
Contribute documentation
========================

You as an end-user of Matplotlib can make a valuable contribution because you
more clearly see the potential for improvement than a core developer. For example, you can:
Expand Down Expand Up @@ -589,23 +592,5 @@ and running the same script will display
my_matplotlib_module.set_range(0, 0) # set range

.. _logging tutorial: https://docs.python.org/3/howto/logging.html#logging-basic-tutorial

.. _sample-data:

Writing examples
----------------

We have hundreds of examples in subdirectories of :file:`matplotlib/examples`,
and these are automatically generated when the website is built to show up in
the :ref:`examples <gallery>` section of the website.

Any sample data that the example uses should be kept small and
distributed with Matplotlib in the
:file:`lib/matplotlib/mpl-data/sample_data/` directory. Then in your
example code you can load it into a file handle with::

import matplotlib.cbook as cbook
fh = cbook.get_sample_data('mydata.dat')

.. _gitter: https://gitter.im/matplotlib/matplotlib
.. _community: https://gitter.im/matplotlib/community
99 changes: 60 additions & 39 deletions doc/devel/documenting_mpl.rst → doc/devel/document.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
.. redirect-from:: /devel/documenting_mpl

.. _documenting-matplotlib:

=====================
Writing documentation
=====================
===================
Write documentation
===================

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

Setting up the doc build
------------------------
Set up the build
----------------

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

Building the docs
-----------------
Build the docs
--------------

The documentation sources are found in the :file:`doc/` directory.
The configuration file for Sphinx is :file:`doc/conf.py`. It controls which
Expand Down Expand Up @@ -105,8 +107,8 @@ On Windows, set the options as environment variables, e.g.:

set SPHINXOPTS= & set O=-j4 -Dplot_formats=png:100 & make html

Showing locally built docs
--------------------------
Show locally built docs
-----------------------

The built docs are available in the folder :file:`build/html`. A shortcut
for opening them in your default browser is:
Expand All @@ -117,8 +119,8 @@ for opening them in your default browser is:

.. _writing-rest-pages:

Writing ReST pages
==================
Write ReST pages
================

Most documentation is either in the docstrings of individual
classes and methods, in explicit ``.rst`` files, or in examples and tutorials.
Expand Down Expand Up @@ -189,8 +191,8 @@ nor the ````literal```` role:

.. _internal-section-refs:

Referring to other documents and sections
-----------------------------------------
Refer to other documents and sections
-------------------------------------

Sphinx_ allows internal references_ between documents.

Expand Down Expand Up @@ -254,8 +256,8 @@ hyphens to separate words.

.. _referring-to-other-code:

Referring to other code
-----------------------
Refer to other code
-------------------

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

.. _rst-figures-and-includes:

Including figures and files
---------------------------
Include figures and files
-------------------------

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

.. _writing-docstrings:

Writing docstrings
==================
Write docstrings
================

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

Referencing types
~~~~~~~~~~~~~~~~~
Reference types
~~~~~~~~~~~~~~~
Generally, the rules from referring-to-other-code_ apply. More specifically:

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

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


Inheriting docstrings
---------------------
Inherit docstrings
------------------

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

.. _docstring-adding-figures:

Adding figures
--------------
Add figures
-----------

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

.. _writing-examples-and-tutorials:

Writing examples and tutorials
==============================
Write examples and tutorials
============================

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

Formatting the example
----------------------
Format examples
---------------

The format of these files is relatively straightforward. Properly
formatted comment blocks are treated as ReST_ text, the code is
Expand Down Expand Up @@ -913,8 +915,26 @@ ReST text are delimited by the line ``# %%`` :

In this way text, code, and figures are output in a "notebook" style.

References for sphinx-gallery
-----------------------------
.. _sample-data:

Sample data
-----------

When sample data comes from a public dataset, please cite the source of the
data. Sample data should be written out in the code. When this is not
feasible, the data can be loaded using `.cbook.get_sample_data`.

.. code-block:: python

import matplotlib.cbook as cbook
fh = cbook.get_sample_data('mydata.dat')


If the data is too large to be included in the code, it should be added to
:file:`lib/matplotlib/mpl-data/sample_data/`

Create mini-gallery
-------------------

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

Order of examples in the gallery
--------------------------------

Order examples
--------------

The order of the sections of the :ref:`tutorials` and the :ref:`gallery`, as
well as the order of the examples within each section are determined in a
Expand Down Expand Up @@ -984,8 +1005,8 @@ manual ``index.rst``.
Miscellaneous
=============

Moving documentation
--------------------
Move documentation
------------------

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

.. _inheritance-diagrams:

Generating inheritance diagrams
-------------------------------
Generate inheritance diagrams
-----------------------------

Class inheritance diagrams can be generated with the Sphinx
`inheritance-diagram`_ directive.
Expand Down
Loading