10 files changed, 178 insertions, 16 deletions
diff --git a/doc/source/_templates/indexcontent.html b/doc/source/_templates/indexcontent.html
index 07fe6d585..fbd8930ae 100644
--- a/doc/source/_templates/indexcontent.html
+++ b/doc/source/_templates/indexcontent.html
@@ -11,6 +11,8 @@
          <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>
 
@@ -34,7 +36,8 @@
     <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="{{ pathto("http://numpy.github.io/neps") }}">NumPy Enhancement Proposals</a><br/>
+      <p class="biglink"><a class="biglink" href="http://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>
       <p class="biglink"><a class="biglink" href="{{ pathto("license") }}">License of NumPy</a></p>
@@ -47,15 +50,11 @@
     <a href="https://archive.org/details/NumPyBook">"Guide to NumPy"</a>
     (which generously entered Public Domain in August 2008). The reference
     documentation for many of the functions are written by numerous
-    contributors and developers of NumPy, both prior to and during the
-    <a href="http://docs.scipy.org/numpy/">NumPy Documentation Marathon</a>.
+    contributors and developers of NumPy.
   </p>
   <p>
     The preferred way to update the documentation is by submitting a pull
-    request on Github (see the 
-    <a href="http://docs.scipy.org/doc/numpy-dev/dev/">Developer Guide</a>.
-    The <a href="http://docs.scipy.org/numpy/">NumPy Documentation Wiki</a>
-    can also still be used to submit documentation fixes.
+    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/conf.py b/doc/source/conf.py
index 7c34a62cd..9e1d1a142 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -22,7 +22,7 @@ sys.path.insert(0, os.path.abspath('../sphinxext'))
 extensions = ['sphinx.ext.autodoc', 'numpydoc',
               'sphinx.ext.intersphinx', 'sphinx.ext.coverage',
               'sphinx.ext.doctest', 'sphinx.ext.autosummary',
-              'sphinx.ext.graphviz',
+              'sphinx.ext.graphviz', 'sphinx.ext.ifconfig',
               'matplotlib.sphinxext.plot_directive']
 
 if sphinx.__version__ >= "1.4":
@@ -39,7 +39,7 @@ source_suffix = '.rst'
 
 # General substitutions.
 project = 'NumPy'
-copyright = '2008-2017, The SciPy community'
+copyright = '2008-2018, The SciPy community'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
@@ -82,6 +82,9 @@ add_function_parentheses = False
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+def setup(app):
+    # add a config value for `ifconfig` directives
+    app.add_config_value('python_version_major', str(sys.version_info.major), 'env')
 
 # -----------------------------------------------------------------------------
 # HTML output
diff --git a/doc/source/dev/gitwash/git_development.rst b/doc/source/dev/gitwash/git_development.rst
index ee7787fec..5d7d47f89 100644
--- a/doc/source/dev/gitwash/git_development.rst
+++ b/doc/source/dev/gitwash/git_development.rst
@@ -11,4 +11,4 @@ Contents:
 
    development_setup
    configure_git
-   development_workflow
+   dot2_dot3
diff --git a/doc/source/dev/gitwash/git_resources.rst b/doc/source/dev/gitwash/git_resources.rst
index 5f0c1d020..c41af762c 100644
--- a/doc/source/dev/gitwash/git_resources.rst
+++ b/doc/source/dev/gitwash/git_resources.rst
@@ -1,8 +1,8 @@
 .. _git-resources:
 
-================
- git_ resources
-================
+=========================
+Additional Git_ Resources
+=========================
 
 Tutorials and summaries
 =======================
diff --git a/doc/source/dev/gitwash/index.rst b/doc/source/dev/gitwash/index.rst
index ae7ce69de..b867bbd97 100644
--- a/doc/source/dev/gitwash/index.rst
+++ b/doc/source/dev/gitwash/index.rst
@@ -11,4 +11,5 @@ Contents:
    git_intro
    following_latest
    git_development
+   development_workflow
    git_resources
diff --git a/doc/source/docs/howto_build_docs.rst b/doc/source/docs/howto_build_docs.rst
new file mode 100644
index 000000000..383bed96d
--- /dev/null
+++ b/doc/source/docs/howto_build_docs.rst
@@ -0,0 +1,87 @@
+.. _howto-build-docs:
+
+=========================================
+Building the NumPy API and reference docs
+=========================================
+
+We currently use Sphinx_ for generating the API and reference
+documentation for NumPy.  You will need Sphinx 1.0.1 or newer.
+
+If you only want to get the documentation, note that pre-built
+versions can be found at
+
+    http://docs.scipy.org/
+
+in several different formats.
+
+.. _Sphinx: http://sphinx.pocoo.org
+
+
+Instructions
+------------
+
+If you obtained NumPy via git, get also the git submodules that contain
+additional parts required for building the documentation::
+
+    git submodule init
+    git submodule update
+
+In addition, building the documentation requires the Sphinx extension
+`plot_directive`, which is shipped with Matplotlib_. This Sphinx extension can
+be installed by installing Matplotlib. You will also need python3.6.
+
+Since large parts of the main documentation are stored in
+docstrings, you will need to first build NumPy, and install it so
+that the correct version is imported by
+
+    >>> import numpy
+
+Note that you can eg. install NumPy to a temporary location and set
+the PYTHONPATH environment variable appropriately.
+
+After NumPy is installed, install SciPy since some of the plots in the random
+module require `scipy.special` to display properly. Now you are ready to
+generate the docs, so write::
+
+    make html
+
+in the ``doc/`` directory. If all goes well, this will generate a
+``build/html`` subdirectory containing the built documentation. Note
+that building the documentation on Windows is currently not actively
+supported, though it should be possible. (See Sphinx_ documentation
+for more information.)
+
+To build the PDF documentation, do instead::
+
+   make latex
+   make -C build/latex all-pdf
+
+You will need to have Latex installed for this.
+
+Instead of the above, you can also do::
+
+   make dist
+
+which will rebuild NumPy, install it to a temporary location, and
+build the documentation in all formats. This will most likely again
+only work on Unix platforms.
+
+The documentation for NumPy distributed at http://docs.scipy.org in html and
+pdf format is also built with ``make dist``.  See `HOWTO RELEASE`_ for details on
+how to update http://docs.scipy.org.
+
+.. _Matplotlib: http://matplotlib.org/
+.. _HOWTO RELEASE: https://github.com/numpy/numpy/blob/master/doc/HOWTO_RELEASE.rst.txt
+
+Sphinx extensions
+-----------------
+
+NumPy's documentation uses several custom extensions to Sphinx.  These
+are shipped in the ``sphinxext/`` directory (as git submodules, as discussed
+above), and are automatically enabled when building NumPy's documentation.
+
+If you want to make use of these extensions in third-party
+projects, they are available on PyPi_ as the numpydoc_ package.
+
+.. _PyPi: http://python.org/pypi
+.. _numpydoc: http://python.org/pypi/numpydoc
diff --git a/doc/source/docs/howto_document.rst b/doc/source/docs/howto_document.rst
new file mode 100644
index 000000000..de7d06cf8
--- /dev/null
+++ b/doc/source/docs/howto_document.rst
@@ -0,0 +1,61 @@
+.. _howto-document:
+
+
+A Guide to NumPy/SciPy Documentation
+====================================
+
+When using `Sphinx <http://sphinx.pocoo.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.
+
+Some features described in this document require a recent version of
+``numpydoc``. For example, the **Yields** section was added in
+``numpydoc`` 0.6.
+
+It is available from:
+
+* `numpydoc on PyPI <http://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.  However, some
+sub-modules, such as ``fft``, are not imported by default, and you have to
+include them explicitly::
+
+  import numpy.fft
+
+after which you may use it::
+
+  np.fft.fft2(...)
+
+.. rubric::
+    **For convenience the** `formatting standard`_ **is included below with an
+    example**
+
+.. include:: ../../sphinxext/doc/format.rst
+
+.. _example:
+
+Example Source
+==============
+
+.. literalinclude:: ../../sphinxext/doc/example.py
+
+
+
+Example Rendered
+================
+
+.. ifconfig:: python_version_major < '3'
+
+    The example is rendered only when sphinx is run with python3 and above
+
+.. automodule:: doc.example
+    :members:
+
+.. _`formatting standard`: https://numpydoc.readthedocs.io/en/latest/format.html
diff --git a/doc/source/docs/index.rst b/doc/source/docs/index.rst
new file mode 100644
index 000000000..7d8b1bcb4
--- /dev/null
+++ b/doc/source/docs/index.rst
@@ -0,0 +1,11 @@
+.. _documentation:
+
+NumPy's Documentation
+=====================
+
+.. toctree::
+    :maxdepth: 2
+
+    howto_document
+    howto_build_docs
+    
diff --git a/doc/source/f2py/python-usage.rst b/doc/source/f2py/python-usage.rst
index 79860173b..60167d01a 100644
--- a/doc/source/f2py/python-usage.rst
+++ b/doc/source/f2py/python-usage.rst
@@ -215,7 +215,7 @@ Sometimes a Fortran package may require that users provide routines
 that the package will use. F2PY can construct an interface to such
 routines so that Python functions could be called from Fortran.
 
-Consider the following `Fortran 77 subroutine`__ that takes an array
+Consider the following Fortran 77 subroutine that takes an array
 and applies a function ``func`` to its elements.
 
   .. include:: calculate.f
diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst
index 67f45a50f..7e1c381d2 100644
--- a/doc/source/user/quickstart.rst
+++ b/doc/source/user/quickstart.rst
@@ -1451,10 +1451,10 @@ that ``pylab.hist`` plots the histogram automatically, while
     >>> mu, sigma = 2, 0.5
     >>> v = np.random.normal(mu,sigma,10000)
     >>> # Plot a normalized histogram with 50 bins
-    >>> plt.hist(v, bins=50, normed=1)       # matplotlib version (plot)
+    >>> plt.hist(v, bins=50, density=1)       # matplotlib version (plot)
     >>> plt.show()
     >>> # Compute the histogram with numpy and then plot it
-    >>> (n, bins) = np.histogram(v, bins=50, normed=True)  # NumPy version (no plot)
+    >>> (n, bins) = np.histogram(v, bins=50, density=True)  # NumPy version (no plot)
     >>> plt.plot(.5*(bins[1:]+bins[:-1]), n)
     >>> plt.show()