150 lines
7.5 KiB
ReStructuredText
150 lines
7.5 KiB
ReStructuredText
.. _howto-docs:
|
|
|
|
############################################
|
|
How to contribute to the NumPy documentation
|
|
############################################
|
|
|
|
The *Documentation* for a software project is the set of reference,
|
|
instructional, educational, informative material generated by the project
|
|
developers and contributors, as well as discussions, presentations, videos and
|
|
other user-generated content. It may include learning-oriented content (such as
|
|
tutorials and how-tos), use-cases or in-depth explanations and reference for
|
|
developers.
|
|
|
|
If you're reading this page, you probably want to help. This guide is meant to
|
|
help you decide which kind of content you'll write, as well as give you some
|
|
tips and instructions for submitting it to the official NumPy documentation
|
|
(that is, the documentation that ships with NumPy and lives on the
|
|
:ref:`official project pages <numpy_docs_mainpage>`). Keep in mind that if you
|
|
don't want to do this, writing a tutorial on your own blog, creating a YouTube
|
|
video or answering questions on social media or Stack Overflow are also great
|
|
contributions!
|
|
|
|
NumPy has a Documentation Team. We have open meetings on Zoom every three weeks
|
|
and invite everyone to join. Don't hesitate to reach out if you have questions
|
|
or just need someone to guide you through your first steps - we're always happy
|
|
to help. Meetings are usually announced on the `numpy-discussion mailing list
|
|
<https://mail.python.org/mailman/listinfo/numpy-discussion>`__. Meeting minutes
|
|
are taken `on hackmd.io <https://hackmd.io/oB_boakvRqKR-_2jRV-Qjg>`__ and stored
|
|
in the `NumPy Archive repository <https://github.com/numpy/archive>`__.
|
|
|
|
You can find larger planned and in-progress documentation improvement ideas `at
|
|
our GitHub project <https://github.com/orgs/numpy/projects/2>`__.
|
|
|
|
Current vision for the documentation: NEP 44
|
|
--------------------------------------------
|
|
|
|
Recently, the NumPy community approved a *NumPy Enhancement Proposal (NEP)*
|
|
about documentation, `NEP 44 - Restructuring the NumPy Documentation
|
|
<https://www.numpy.org/neps/nep-0044-restructuring-numpy-docs>`__.
|
|
|
|
**Where is the documentation?**
|
|
|
|
The main page for the :ref:`NumPy Documentation <numpy_docs_mainpage>` lists
|
|
several categories. The documents mentioned there live in different places.
|
|
|
|
- **Tutorials, How-Tos, Explanations:** These documents are stored in the NumPy
|
|
source code tree, which means that in order to add them to the official
|
|
documentation, you have to download the NumPy source code,
|
|
:ref:`build it <howto-build-docs>` and submit your changes via a
|
|
:ref:`GitHub pull request <devindex>`.
|
|
|
|
- **API Reference:** These are mainly the result of rendering the NumPy code
|
|
`docstrings <https://www.python.org/dev/peps/pep-0257/>`__ into formatted
|
|
documents. They are automatically generated when the NumPy documentation is
|
|
:ref:`built from source<howto-build-docs>`.
|
|
|
|
**Datasets**
|
|
|
|
If you are writing a tutorial or how-to, we encourage you to use real images and
|
|
data (provided they are appropriately licensed and available). This makes the
|
|
material more engaging for readers, and choosing the right data can add
|
|
pedagogical value to your content.
|
|
|
|
*Note: currently we cannot easily use data in other packages (except, e.g., from
|
|
SciPy or Matplotlib). We plan to create a dedicated datasets package, but that's
|
|
not ready yet - please discuss with us if you have data sources in mind.*
|
|
|
|
Creating new content
|
|
--------------------
|
|
|
|
The documentation is written in restructuredText, which is the format required
|
|
by Sphinx, the tool most Python projects use to automatically build and link the
|
|
documentation within the project. You can read the
|
|
`Quick reStructuredText Guide
|
|
<https://docutils.sourceforge.io/docs/user/rst/quickref.html>`__ or the
|
|
`reStructuredText Primer
|
|
<http://www.sphinx-doc.org/en/stable/usage/restructuredtext/basics.html>`__ for
|
|
more information.
|
|
|
|
If you have already decided which type of document you want to write, you can
|
|
check out the following specific guides:
|
|
|
|
- Guide to writing Tutorials (TODO)
|
|
- :ref:`Guide to writing reference (API) documentation: the numpydoc docstring
|
|
guide <howto-document>`
|
|
|
|
Major additions to the documentation (e.g. new tutorials) should be proposed to
|
|
the `mailing list
|
|
<https://mail.python.org/mailman/listinfo/numpy-discussion>`__.
|
|
|
|
Other ways to contribute
|
|
------------------------
|
|
|
|
Correcting technical inaccuracies in the documentation are high priority. For
|
|
example, if a docstring is missing a parameter or the description of a
|
|
fuction/parameter/method etc. is incorrect. Other "structural" defects like
|
|
broken links are also high priority.
|
|
|
|
Proposals for changes that improve the clarity of the documentation are welcome.
|
|
However, "clarity" is a bit subjective, so such proposals are best made by
|
|
raising issues that describe what could be improved in the current
|
|
documentation. Proposals that include specific suggestions for the improvement
|
|
are encouraged as the proposed changes helps frame the discussion.
|
|
|
|
Based on the above characterization, "high-priority" changes (i.e. fixing
|
|
technical inaccuracies, broken links, etc.) can be proposed via pull requests
|
|
directly as they are straightforward to review. Other changes should be raised
|
|
as issues first so that the discussion can happen before you make major
|
|
modifications, which in principle saves you from wasting your time on
|
|
undesired changes.
|
|
|
|
If you see a good tutorial, how-to or explanation that is not included in the
|
|
official documentation, you can suggest it to be added by `opening an issue on
|
|
GitHub <https://github.com/numpy/numpy/issues>`__. Similarly, opening issues to
|
|
suggest a tutorial, how-to or explanation that you can't find anywhere is a
|
|
great way to help the documentation team direct efforts towards what users are
|
|
looking for. `See this issue <https://github.com/numpy/numpy/issues/15760>`__
|
|
for an example of how to do this.
|
|
|
|
Finally, if you detect a typo or an error in the documentation, or would like to
|
|
suggest a different approach, you can also open an issue or submit a pull
|
|
request with your suggestion. Keep in mind that changes fixing
|
|
grammatical/spelling errors are welcome but not necessarily the highest
|
|
priority. "Grammatical correctness" often gets confused with "style" which can
|
|
result in unfruitful discussions that don't necessarily improve anything.
|
|
Changes that modify wording or rearrange phrasing without changing the technical
|
|
content are discouraged. If you think that a different wording improves clarity,
|
|
you should open an issue as noted above, but again, changes along these lines
|
|
very often tend to be highly subjective and not necessarily do much to improve
|
|
the quality of the documentation.
|
|
|
|
**Final tips**
|
|
|
|
- Don't worry if English is not your first language. Do your best - we'll revise
|
|
your content and make sure we fix any issues with the code or text.
|
|
- If you are unsure whether your tutorial is useful to the community, consider
|
|
submitting an issue on GitHub suggesting it, or asking on the mailing
|
|
list or Stack Overflow.
|
|
- If you are unfamiliar with git/GitHub or the process of submitting a pull
|
|
request (PR), check our :ref:`Contributor Guide <devindex>`.
|
|
|
|
**Other interesting material**
|
|
|
|
- `writethedocs.org <https://www.writethedocs.org/>`__ has a lot of interesting
|
|
resources for technical writing.
|
|
- Google offers two free `Technical Writing Courses
|
|
<https://developers.google.com/tech-writing>`__
|
|
- `Software Carpentry <https://software-carpentry.org/software>`__ has a lot of
|
|
nice recommendations for creating educational material.
|