Fix some doc build warnings

Author: jakevdp

docs/CHANGELOG.rst

@@ -17,15 +17,15 @@ jax 0.2.9 (Unreleased)
 
 * Breaking changes:
 
-  * ``jax.ops.segment_sum` now drops segment IDs that are out of range rather
+  * :func:`jax.ops.segment_sum` now drops segment IDs that are out of range rather
     than wrapping them into the segment ID space. This was done for performance
     reasons.
 
 * `GitHub commits <https://github.com/google/jax/compare/jax-v0.2.8...jax-v0.2.9>`__.
 
 * New features:
 
-  * Extend the `jax.experimental.loops` module with support for pytrees. Improved
+  * Extend the :mod:`jax.experimental.loops` module with support for pytrees. Improved
     error checking and error messages.
 
   * Add :func:`jax.experimental.enable_x64` and :func:`jax.experimental.disable_x64`.
@@ -78,7 +78,7 @@ jax 0.2.8 (January 12 2021)
 
 * New features:
 
-  * New flag for debugging ``inf``s, analagous to that for ``NaN``s (`#5224 <https://github.com/google/jax/pull/5224>`_).
+  * New flag for debugging ``inf``, analagous to that for ``NaN`` (`#5224 <https://github.com/google/jax/pull/5224>`_).
 
 jax 0.2.7 (Dec 4 2020)
 ----------------------
@@ -437,7 +437,7 @@ jax 0.1.67 (May 12, 2020)
 
 * Notable changes:
 
-  * The visibility of names exported from :py:module:`jax.numpy` has been
+  * The visibility of names exported from :mod:`jax.numpy` has been
     tightened. This may break code that was making use of names that were
     previously exported accidentally.
 
@@ -585,7 +585,7 @@ jax 0.1.60 (March 17, 2020)
     ``static_argnums`` in :py:func:`jax.jit`.
   * Improved error messages for when tracers are mistakenly saved in global state.
   * Added :py:func:`jax.nn.one_hot` utility function.
-  * Added :py:module:`jax.experimental.jet` for exponentially faster
+  * Added :mod:`jax.experimental.jet` for exponentially faster
     higher-order automatic differentiation.
   * Added more correctness checking to arguments of :py:func:`jax.lax.broadcast_in_dim`.
 

docs/conf.py

@@ -109,6 +109,8 @@
     'notebooks/XLA_in_Python.ipynb',
     # Sometimes sphinx reads its own outputs as inputs!
     'build/html',
+    'notebooks/README.md',
+    'README.md',
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.

docs/developer.rst

@@ -82,7 +82,7 @@ to set up a CUDA environment.
 You can either install Python using its
 `Windows installer <https://www.python.org/downloads/>`_, or if you prefer, you
 can use `Anaconda <https://docs.anaconda.com/anaconda/install/windows/>`_
-or `Miniconda <https://docs.conda.io/en/latest/miniconda.html#windows-installers>`_
+or `Miniconda <https://docs.conda.io/en/latest/miniconda.html#windows-installers>`__
 to setup a Python environment.
 
 Some targets of Bazel use bash utilities to do scripting, so `MSYS2 <https://www.msys2.org>`_
@@ -186,7 +186,7 @@ To rebuild the documentation, install several packages::
 
 You must also install ``pandoc`` in order to regenerate the notebooks.
 See `Install Pandoc <https://pandoc.org/installing.html>`_,
-or using `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_ which
+or using `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`__ which
 I have used successfully on the Mac: ``conda install -c conda-forge pandoc``.
 If you do not want to install ``pandoc`` then you should regenerate the documentation
 without the notebooks.

docs/index.rst

@@ -42,6 +42,7 @@ For an introduction to JAX, start at the
    pytrees
    rank_promotion_warning
    type_promotion
+   custom_vjp_update
 
 .. toctree::
    :maxdepth: 2

jax/_src/ops/scatter.py

@@ -107,6 +107,7 @@ def index_add(x, idx, y, indices_are_sorted=False, unique_indices=False):
 
   Returns the value of `x` that would result from the
   NumPy-style :mod:`indexed assignment <numpy.doc.indexing>`::
+
     x[idx] += y
 
   Note the `index_add` operator is pure; `x` itself is
@@ -149,6 +150,7 @@ def index_mul(x, idx, y, indices_are_sorted=False, unique_indices=False):
 
   Returns the value of `x` that would result from the
   NumPy-style :mod:`indexed assignment <numpy.doc.indexing>`::
+
     x[idx] *= y
 
   Note the `index_mul` operator is pure; `x` itself is
@@ -191,6 +193,7 @@ def index_min(x, idx, y, indices_are_sorted=False, unique_indices=False):
 
   Returns the value of `x` that would result from the
   NumPy-style :mod:`indexed assignment <numpy.doc.indexing>`::
+
     x[idx] = minimum(x[idx], y)
 
   Note the `index_min` operator is pure; `x` itself is
@@ -230,6 +233,7 @@ def index_max(x, idx, y, indices_are_sorted=False, unique_indices=False):
 
   Returns the value of `x` that would result from the
   NumPy-style :mod:`indexed assignment <numpy.doc.indexing>`::
+
     x[idx] = maximum(x[idx], y)
 
   Note the `index_max` operator is pure; `x` itself is
@@ -269,6 +273,7 @@ def index_update(x, idx, y, indices_are_sorted=False, unique_indices=False):
 
   Returns the value of `x` that would result from the
   NumPy-style :mod:`indexed assignment <numpy.doc.indexing>`::
+
     x[idx] = y
 
   Note the `index_update` operator is pure; `x` itself is

jax/_src/scipy/linalg.py

@@ -245,8 +245,9 @@ def triu(m, k=0):
 
 The number of required squarings = max(0, ceil(log2(norm(A)) - c)
 where norm() denotes the L1 norm, and
-  c=2.42 for float64 or complex128,
-  c=1.97 for float32 or complex64
+
+- c=2.42 for float64 or complex128,
+- c=1.97 for float32 or complex64
 """)
 
 @_wraps(scipy.linalg.expm, lax_description=_expm_description)