1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
.. _howto-docs:
############################################
How to contribute to the NumPy documentation
############################################
This guide will help you decide what to contribute and how to submit it to the
official NumPy documentation.
***************************
Documentation team meetings
***************************
The NumPy community has set a firm goal of improving its documentation. We
hold regular documentation meetings on Zoom (dates are announced on the
`numpy-discussion mailing list
<https://mail.python.org/mailman/listinfo/numpy-discussion>`__), and everyone
is welcome. Reach out if you have questions or need
someone to guide you through your first steps -- we're happy to help.
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>`__.
*************
What's needed
*************
The :ref:`NumPy Documentation <numpy_docs_mainpage>` has the details covered.
API reference documentation is generated directly from
`docstrings <https://www.python.org/dev/peps/pep-0257/>`_ in the code when the
documentation is :ref:`built<howto-build-docs>`. Although we have mostly
complete reference documentation for each function and class exposed to users,
there is a lack of usage examples for some of them.
What we lack are docs with broader scope -- tutorials, how-tos, and
explanations. Reporting defects is another way to contribute. We discuss both.
******************
Contributing fixes
******************
We're eager to hear about and fix doc defects. But to attack the biggest
problems we end up having to defer or overlook some bug reports. Here are the
best defects to go after.
Top priority goes to **technical inaccuracies** -- a docstring missing a
parameter, a faulty description of a function/parameter/method, and so on.
Other "structural" defects like broken links also get priority. All these fixes
are easy to confirm and put in place. You can submit
a `pull request (PR) <https://numpy.org/devdocs/dev/index.html#devindex>`__
with the fix, if you know how to do that; otherwise please `open an issue
<https://github.com/numpy/numpy/issues>`__.
**Typos and misspellings** fall on a lower rung; we welcome hearing about them
but may not be able to fix them promptly. These too can be handled as pull
requests or issues.
Obvious **wording** mistakes (like leaving out a "not") fall into the typo
category, but other rewordings -- even for grammar -- require a judgment call,
which raises the bar. Test the waters by first presenting the fix as an issue.
Some functions/objects like numpy.ndarray.transpose, numpy.array etc. defined in
C-extension modules have their docstrings defined seperately in `_add_newdocs.py
<https://github.com/numpy/numpy/blob/main/numpy/core/_add_newdocs.py>`__
**********************
Contributing new pages
**********************
Your frustrations using our documents are our best guide to what needs fixing.
If you write a missing doc you join the front line of open source, but it's
a meaningful contribution just to let us know what's missing. If you want to
compose a doc, run your thoughts by the `mailing list
<https://mail.python.org/mailman/listinfo/numpy-discussion>`__ for futher
ideas and feedback. If you want to alert us to a gap,
`open an issue <https://github.com/numpy/numpy/issues>`__. See
`this issue <https://github.com/numpy/numpy/issues/15760>`__ for an example.
If you're looking for subjects, our formal roadmap for documentation is a
*NumPy Enhancement Proposal (NEP)*,
`NEP 44 - Restructuring the NumPy Documentation <https://www.numpy.org/neps/nep-0044-restructuring-numpy-docs>`__.
It identifies areas where our docs need help and lists several
additions we'd like to see, including :ref:`Jupyter notebooks <numpy_tutorials>`.
.. _tutorials_howtos_explanations:
Documentation framework
=======================
There are formulas for writing useful documents, and four formulas
cover nearly everything. There are four formulas because there are four
categories of document -- ``tutorial``, ``how-to guide``, ``explanation``,
and ``reference``. The insight that docs divide up this way belongs to
Daniele Procida and his `Diátaxis Framework <https://diataxis.fr/>`__. When you
begin a document or propose one, have in mind which of these types it will be.
.. _numpy_tutorials:
NumPy tutorials
===============
In addition to the documentation that is part of the NumPy source tree, you can
submit content in Jupyter Notebook format to the
`NumPy Tutorials <https://numpy.org/numpy-tutorials>`__ page. This
set of tutorials and educational materials is meant to provide high-quality
resources by the NumPy project, both for self-learning and for teaching classes
with. These resources are developed in a separate GitHub repository,
`numpy-tutorials <https://github.com/numpy/numpy-tutorials>`__, where you can
check out existing notebooks, open issues to suggest new topics or submit your
own tutorials as pull requests.
.. _contributing:
More on contributing
====================
Don't worry if English is not your first language, or if you can only come up
with a rough draft. Open source is a community effort. Do your best -- we'll
help fix issues.
Images and real-life data make text more engaging and powerful, but be sure
what you use is appropriately licensed and available. Here again, even a rough
idea for artwork can be polished by others.
For now, the only data formats accepted by NumPy are those also used by other
Python scientific libraries like pandas, SciPy, or Matplotlib. We're
developing a package to accept more formats; contact us for details.
NumPy documentation is kept in the source code tree. To get your document
into the docbase you must download the tree, :ref:`build it
<howto-build-docs>`, and submit a pull request. If GitHub and pull requests
are new to you, check our :ref:`Contributor Guide <devindex>`.
Our markup language is reStructuredText (rST), which is more elaborate than
Markdown. Sphinx, the tool many Python projects use to build and link project
documentation, converts the rST into HTML and other formats. For more on
rST, see 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>`__
***********************
Contributing indirectly
***********************
If you run across outside material that would be a useful addition to the
NumPy docs, let us know by `opening an issue <https://github.com/numpy/numpy/issues>`__.
You don't have to contribute here to contribute to NumPy. You've contributed
if you write a tutorial on your blog, create a YouTube video, or answer questions
on Stack Overflow and other sites.
.. _howto-document:
*******************
Documentation style
*******************
.. _userdoc_guide:
User documentation
==================
- In general, we follow the
`Google developer documentation style guide <https://developers.google.com/style>`_
for the User Guide.
- NumPy style governs cases where:
- Google has no guidance, or
- We prefer not to use the Google style
Our current rules:
- We pluralize *index* as *indices* rather than
`indexes <https://developers.google.com/style/word-list#letter-i>`_,
following the precedent of :func:`numpy.indices`.
- For consistency we also pluralize *matrix* as *matrices*.
- Grammatical issues inadequately addressed by the NumPy or Google rules are
decided by the section on "Grammar and Usage" in the most recent edition of
the `Chicago Manual of Style
<https://en.wikipedia.org/wiki/The_Chicago_Manual_of_Style>`_.
- We welcome being
`alerted <https://github.com/numpy/numpy/issues>`_ to cases
we should add to the NumPy style rules.
.. _docstring_intro:
Docstrings
==========
When using `Sphinx <http://www.sphinx-doc.org/>`_ in combination with the
NumPy conventions, you should use the ``numpydoc`` extension so that your
docstrings will be handled correctly. For example, Sphinx will extract the
``Parameters`` section from your docstring and convert it into a field
list. Using ``numpydoc`` will also avoid the reStructuredText errors produced
by plain Sphinx when it encounters NumPy docstring conventions like
section headers (e.g. ``-------------``) that sphinx does not expect to
find in docstrings.
It is available from:
* `numpydoc on PyPI <https://pypi.python.org/pypi/numpydoc>`_
* `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_
Note that for documentation within NumPy, it is not necessary to do
``import numpy as np`` at the beginning of an example.
Please use the ``numpydoc`` :ref:`formatting standard <numpydoc:format>` as
shown in their :ref:`example <numpydoc:example>`.
*********************
Documentation reading
*********************
- The leading organization of technical writers,
`Write the Docs <https://www.writethedocs.org/>`__,
holds conferences, hosts learning resources, and runs a Slack channel.
- "Every engineer is also a writer," says Google's
`collection of technical writing resources <https://developers.google.com/tech-writing>`__,
which includes free online courses for developers in planning and writing
documents.
- `Software Carpentry's <https://software-carpentry.org/lessons>`__ mission is
teaching software to researchers. In addition to hosting the curriculum, the
website explains how to present ideas effectively.
|
