diff options
| -rw-r--r-- | doc/source/contents.rst | 8 | ||||
| -rw-r--r-- | doc/source/dev/howto-docs.rst | 149 | ||||
| -rw-r--r-- | doc/source/dev/index.rst | 3 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 2 |
4 files changed, 157 insertions, 5 deletions
diff --git a/doc/source/contents.rst b/doc/source/contents.rst index c89153aa7..baea7784c 100644 --- a/doc/source/contents.rst +++ b/doc/source/contents.rst @@ -1,8 +1,8 @@ -.. _manual: +.. _numpy_docs_mainpage: -##################### -NumPy manual contents -##################### +################### +NumPy Documentation +################### .. toctree:: diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst new file mode 100644 index 000000000..0e2e03e0b --- /dev/null +++ b/doc/source/dev/howto-docs.rst @@ -0,0 +1,149 @@ +.. _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. diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst index dc6099992..5270bfb77 100644 --- a/doc/source/dev/index.rst +++ b/doc/source/dev/index.rst @@ -1,3 +1,5 @@ +.. _devindex: + ##################### Contributing to NumPy ##################### @@ -284,6 +286,7 @@ The rest of the story style_guide releasing governance/index + howto-docs NumPy-specific workflow is in :ref:`numpy-development-workflow <development-workflow>`. diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index d042a1849..1ae205f91 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -12,7 +12,7 @@ NumPy Reference This reference manual details functions, modules, and objects included in NumPy, describing what they are and what they do. -For learning how to use NumPy, see the :ref:`complete documentation <manual>`. +For learning how to use NumPy, see the :ref:`complete documentation <numpy_docs_mainpage>`. .. toctree:: |