diff options
| -rw-r--r-- | doc/source/_templates/indexcontent.html | 68 | ||||
| -rw-r--r-- | doc/source/contents.rst | 17 | ||||
| -rw-r--r-- | doc/source/dev/underthehood.rst | 7 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 2 | ||||
| -rw-r--r-- | doc/source/user/explanations_index.rst | 14 | ||||
| -rw-r--r-- | doc/source/user/howtos_index.rst | 14 | ||||
| -rw-r--r-- | doc/source/user/index.rst | 23 | ||||
| -rw-r--r-- | doc/source/user/ionumpy.rst | 20 | ||||
| -rw-r--r-- | doc/source/user/quickstart.rst | 18 | ||||
| -rw-r--r-- | doc/source/user/tutorials_index.rst | 19 |
10 files changed, 144 insertions, 58 deletions
diff --git a/doc/source/_templates/indexcontent.html b/doc/source/_templates/indexcontent.html index 294d39233..d77c5a85e 100644 --- a/doc/source/_templates/indexcontent.html +++ b/doc/source/_templates/indexcontent.html @@ -1,35 +1,43 @@ {% extends "defindex.html" %} {% block tables %} - <p><strong>Parts of the documentation:</strong></p> - <table class="contentstable" align="center"><tr> +<p><strong>For users:</strong></p> +<table class="contentstable" align="center"><tr> <td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("user/index") }}">NumPy User Guide</a><br/> - <span class="linkdescr">start here</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">NumPy Reference</a><br/> - <span class="linkdescr">reference documentation</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("benchmarking") }}">Benchmarking</a><br/> - <span class="linkdescr">benchmarking NumPy</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/setting-up") }}">Setting Up</a><br/> + <span class="linkdescr">Learn about what NumPy is and how to install it</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/quickstart") }}">Quickstart Tutorial</a><br/> + <span class="linkdescr">Aimed at domain experts or people migrating to NumPy</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/absolute_beginners") }}">Absolute Beginners Tutorial</a><br/> + <span class="linkdescr">Start here for an overview of NumPy features and syntax</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/tutorials_index") }}">Tutorials</a><br/> + <span class="linkdescr">Learn about concepts and submodules</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/howtos_index") }}">How Tos</a><br/> + <span class="linkdescr">How to do common tasks with NumPy</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">NumPy API Reference</a><br/> + <span class="linkdescr">Automatically generated reference documentation</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/explanations_index") }}">Explanations</a><br/> + <span class="linkdescr">In depth explanation of concepts, best practices and techniques</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("f2py/index") }}">F2Py Guide</a><br/> - <span class="linkdescr">f2py documentation</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("dev/index") }}">NumPy Developer Guide</a><br/> - <span class="linkdescr">contributing to NumPy</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("docs/index") }}">Building and Extending the Documentation</a><br/> - <span class="linkdescr">about this documentation</span></p> - </td></tr> - </table> + <span class="linkdescr">Documentation for the f2py module (Fortran extensions for Python)</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">Glossary</a><br/> + <span class="linkdescr">List of the most important terms</span></p> + </td></tr> +</table> - <p><strong>Indices and tables:</strong></p> - <table class="contentstable" align="center"><tr> +<p><strong>For developers/contributors:</strong></p> +<table class="contentstable" align="center"><tr> <td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/> - <span class="linkdescr">all functions, classes, terms</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">Glossary</a><br/> - <span class="linkdescr">the most important terms explained</span></p> - </td><td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/> - <span class="linkdescr">search this documentation</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Complete Table of Contents</a><br/> - <span class="linkdescr">lists all sections and subsections</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("dev/index") }}">NumPy Contributor Guide</a><br/> + <span class="linkdescr">Contributing to NumPy</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("dev/underthehood") }}">Under-the-hood docs</a><br/> + <span class="linkdescr">Specialized, in-depth documentation</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("docs/index") }}">Building and Extending the Documentation</a><br/> + <span class="linkdescr">How to contribute to this documentation (user and API)</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("docs/howto_document") }}">The numpydoc docstring guide</a><br/> + <span class="linkdescr">How to write docstrings in the numpydoc format</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("benchmarking") }}">Benchmarking</a><br/> + <span class="linkdescr">benchmarking NumPy</span></p> + <p class="biglink"><a class="biglink" href="https://www.numpy.org/neps/index.html">NumPy Enhancement Proposals</a><br/> </td></tr> </table> @@ -37,11 +45,9 @@ <table class="contentstable" align="center"><tr> <td width="50%"> <p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">Reporting bugs</a></p> - <p class="biglink"><a class="biglink" href="{{ pathto("about") }}">About NumPy</a></p> - <p class="biglink"><a class="biglink" href="https://www.numpy.org/neps/index.html"> - NumPy Enhancement Proposals</a><br/> - </td><td width="50%"> <p class="biglink"><a class="biglink" href="{{ pathto("release") }}">Release Notes</a></p> + </td><td width="50%"> + <p class="biglink"><a class="biglink" href="{{ pathto("about") }}">About NumPy</a></p> <p class="biglink"><a class="biglink" href="{{ pathto("license") }}">License of NumPy</a></p> </td></tr> </table> @@ -56,7 +62,7 @@ </p> <p> The preferred way to update the documentation is by submitting a pull - request on Github (see the <a href="{{ pathto("docs/index") }}">Documentation Index</a>. + request on Github (see the <a href="{{ pathto("docs/index") }}">Documentation Index</a>). Please help us to further improve the NumPy documentation! </p> {% endblock %} diff --git a/doc/source/contents.rst b/doc/source/contents.rst index 019dcc71d..c89153aa7 100644 --- a/doc/source/contents.rst +++ b/doc/source/contents.rst @@ -1,16 +1,27 @@ +.. _manual: + ##################### NumPy manual contents ##################### .. toctree:: - user/index + user/setting-up + user/quickstart + user/absolute_beginners + user/tutorials_index + user/howtos_index reference/index + user/explanations_index f2py/index + glossary dev/index + dev/underthehood docs/index + docs/howto_document + benchmarking + bugs release about - bugs license - glossary + diff --git a/doc/source/dev/underthehood.rst b/doc/source/dev/underthehood.rst new file mode 100644 index 000000000..4dae48689 --- /dev/null +++ b/doc/source/dev/underthehood.rst @@ -0,0 +1,7 @@ +.. _underthehood: + +=========================================== +Under-the-hood Documentation for developers +=========================================== + +To be completed. diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 6742d605a..d042a1849 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 also :ref:`user`. +For learning how to use NumPy, see the :ref:`complete documentation <manual>`. .. toctree:: diff --git a/doc/source/user/explanations_index.rst b/doc/source/user/explanations_index.rst new file mode 100644 index 000000000..f515e36b1 --- /dev/null +++ b/doc/source/user/explanations_index.rst @@ -0,0 +1,14 @@ +.. _explanations: + +################ +Explanations +################ + +These documents are intended to explain in detail the concepts and techniques +used in NumPy. For the reference documentation of the functions and classes +contained in the package, see the :ref:`API reference <reference>`. + +.. toctree:: + :maxdepth: 1 + + basics.broadcasting diff --git a/doc/source/user/howtos_index.rst b/doc/source/user/howtos_index.rst new file mode 100644 index 000000000..c052286b9 --- /dev/null +++ b/doc/source/user/howtos_index.rst @@ -0,0 +1,14 @@ +.. _howtos: + +################ +NumPy How Tos +################ + +These documents are intended as recipes to common tasks using NumPy. For +detailed reference documentation of the functions and classes contained in +the package, see the :ref:`API reference <reference>`. + +.. toctree:: + :maxdepth: 1 + + ionumpy diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst deleted file mode 100644 index d506a5a98..000000000 --- a/doc/source/user/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _user: - -################ -NumPy User Guide -################ - -This guide is intended as an introductory overview of NumPy and -explains how to install and make use of the most important features of -NumPy. For detailed reference documentation of the functions and -classes contained in the package, see the :ref:`reference`. - -.. toctree:: - :maxdepth: 1 - - setting-up - quickstart - absolute_beginners - basics - misc - numpy-for-matlab-users - tutorial-svd - building - c-info diff --git a/doc/source/user/ionumpy.rst b/doc/source/user/ionumpy.rst new file mode 100644 index 000000000..a31720322 --- /dev/null +++ b/doc/source/user/ionumpy.rst @@ -0,0 +1,20 @@ +================================================ +How to read and write data using NumPy +================================================ + +.. currentmodule:: numpy + +.. testsetup:: + + import numpy as np + np.random.seed(1) + +**Objectives** + +- Writing NumPy arrays to files +- Reading NumPy arrays from files +- Dealing with encoding and dtype issues + +**Content** + +To be completed. diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst index 05a247f8a..dd824e14b 100644 --- a/doc/source/user/quickstart.rst +++ b/doc/source/user/quickstart.rst @@ -21,6 +21,24 @@ If you wish to work the examples in this tutorial, you must also have some software installed on your computer. Please see https://scipy.org/install.html for instructions. +**Learner profile** + +This tutorial is intended as a quick overview of +algebra and arrays in NumPy and want to understand how n-dimensional +(:math:`n>=2`) arrays are represented and can be manipulated. In particular, if +you don't know how to apply common functions to n-dimensional arrays (without +using for-loops), or if you want to understand axis and shape properties for +n-dimensional arrays, this tutorial might be of help. + +**Learning Objectives** + +After this tutorial, you should be able to: + +- Understand the difference between one-, two- and n-dimensional arrays in + NumPy; +- Understand how to apply some linear algebra operations to n-dimensional + arrays without using for-loops; +- Understand axis and shape properties for n-dimensional arrays. .. _quickstart.the-basics: diff --git a/doc/source/user/tutorials_index.rst b/doc/source/user/tutorials_index.rst new file mode 100644 index 000000000..c5e859fad --- /dev/null +++ b/doc/source/user/tutorials_index.rst @@ -0,0 +1,19 @@ +.. _tutorials: + +################ +NumPy Tutorials +################ + +These documents are intended as an introductory overview of NumPy and its +features. For detailed reference documentation of the functions and +classes contained in the package, see the :ref:`API reference <reference>`. + +.. toctree:: + :maxdepth: 1 + + basics + misc + numpy-for-matlab-users + tutorial-svd + building + c-info |