manual curation of docs to eliminate 90% of warnings

doc/conf.py

@@ -113,7 +113,8 @@ pygments_style = "sphinx"
 
 # html4_writer added to Fix colon & whitespace misalignment
 # https://github.com/readthedocs/sphinx_rtd_theme/issues/766#issuecomment-513852197
-html4_writer = True
+# https://github.com/readthedocs/sphinx_rtd_theme/issues/766#issuecomment-629666319
+# html4_writer = False
 
 html_logo = "images/pytensor_logo.svg"
 html_theme = "pymc_sphinx_theme"

doc/environment.yml

@@ -9,7 +9,7 @@ dependencies:
   - numpy
   - scipy
   - six
-  - sphinx>=3
+  - sphinx>=5.1.0
   - mock
   - pillow
   - pip

doc/extending/type.rst

@@ -324,8 +324,8 @@ For certain mechanisms, you can register functions and other such
 things to plus your type into pytensor's mechanisms.  These are optional
 but will allow people to use you type with familiar interfaces.
 
-`transfer`
-~~~~~~~~~~
+**`transfer`**
+
 
 To plug in additional options for the transfer target, define a
 function which takes an PyTensor variable and a target argument and

doc/extending/using_params.rst

@@ -76,7 +76,6 @@ attribute :attr:`params_type` to an instance of your params Type.
    If you want to have multiple parameters, PyTensor provides the convenient class
    :class:`pytensor.link.c.params_type.ParamsType` that allows to bundle many parameters into
    one object that will be available in both Python (as a Python object) and C code (as a struct).
-   See :ref:`ParamsType tutorial and API documentation <libdoc_graph_params_type>` for more infos.
 
 For example if we decide to use an int as the params the following
 would be appropriate:

doc/library/compile/io.rst

@@ -6,9 +6,9 @@
 
 .. _function_inputs:
 
-===========================================
+============================================
 :mod:`io` - defines pytensor.function [TODO]
-===========================================
+============================================
 
 .. module:: pytensor.compile.io
    :platform: Unix, Windows

doc/library/compile/opfromgraph.rst

@@ -2,9 +2,9 @@
 
 .. _opfromgraph:
 
-============
+=============
 `OpFromGraph`
-============
+=============
 
 This page describes :class:`pytensor.compile.builders.OpFromGraph
 <pytensor.compile.builders.OpFromGraph>`, an `Op` constructor that allows one to

doc/library/graph/index.rst

@@ -18,5 +18,4 @@
     features
     op
     type
-    params_type
     utils

doc/library/graph/params_type.rst

-.. _libdoc_graph_params_type:
-
-=======================================================================
-:mod:`pytensor.graph.params_type` -- Wrapper class for :class:`Op` params
-=======================================================================
-
----------
-Reference
----------
-
-.. automodule:: pytensor.graph.params_type
-   :platform: Unix, Windows
-   :synopsis: Wrapper class for op params
-   :members:
-   :member-order: bysource
-.. moduleauthor:: LISA

doc/library/index.rst

@@ -19,7 +19,6 @@ Modules
    config
    d3viz/index
    graph/index
-   gpuarray/index
    gradient
    misc/pkl_utils
    printing

doc/library/sandbox/index.rst

@@ -14,4 +14,3 @@
     :maxdepth: 1
 
     linalg
-    neighbours

doc/library/tensor/basic.rst

@@ -557,6 +557,7 @@ them perfectly, but a `dscalar` otherwise.
     .. method:: astype(dtype)
     .. method:: take(indices, axis=None, mode='raise')
     .. method:: copy()
+       :noindex:
 
         Return a new symbolic variable that is a copy of the variable. Does not copy the tag.
 
@@ -667,11 +668,7 @@ dimensions, see :meth:`_tensor_py_operators.dimshuffle`.
     >>> pytensor.tensor.shape_padaxis(tensor, axis=-1)
     InplaceDimShuffle{0,1,2,x}.0
 
-.. autofunction:: unbroadcast(x, *axes)
-
-.. autofunction:: addbroadcast(x, *axes)
-
-.. autofunction:: patternbroadcast(x, broadcastable)
+.. autofunction:: specify_shape(x, shape)
 
 .. function:: flatten(x, ndim=1)
 

doc/sandbox/sparse.rst

@@ -120,7 +120,7 @@ Misc
 The sparse equivalent of `dmatrix` is `csc_matrix` and `csr_matrix`.
 
 :class:`~pytensor.sparse.basic.Dot` vs. :class:`~pytensor.sparse.basic.StructuredDot`
----------------------------------------------------------------------------------
+-------------------------------------------------------------------------------------
 
 Often when you use a sparse matrix it is because there is a meaning to the
 structure of non-zeros. The gradient on terms outside that structure

doc/troubleshooting.rst

@@ -16,7 +16,7 @@ Here are Linux troubleshooting instructions. There is a specific `MacOS`_ sectio
 .. _network_error_proxy:
 
 Why do I get a network error when I install PyTensor
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you are behind a proxy, you must do some extra configuration steps
 before starting the installation. You must set the environment
@@ -69,7 +69,7 @@ large enough.
 .. _float64_output:
 
 pytensor.function returns a float64 when the inputs are float32 and int{32, 64}
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 It should be noted that using float32 and int{32, 64} together
 inside a function would provide float64 as output.
@@ -80,7 +80,7 @@ To help you find where float64 are created, see the
 .. _test_pytensor:
 
 How to test that PyTensor works properly
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 An easy way to check something that could be wrong is by making sure ``PYTENSOR_FLAGS``
 have the desired values as well as the ``~/.pytensorrc``

doc/tutorial/profiling.rst

@@ -27,6 +27,7 @@ of the following two options:
 2. Pass the argument :attr:`profile=True` to the function :func:`pytensor.function
    <function.function>` and then call :attr:`f.profile.summary()` for a single
    function.
+
    - Use this option when you want to profile not all the
      functions but only one or more specific function(s).
    - You can also combine the profile results of many functions:

environment.yml

@@ -31,7 +31,7 @@ dependencies:
   - pytest-cov
   - pytest-xdist
   # For building docs
-  - sphinx>=1.3
+  - sphinx>=5.1.0
   - sphinx_rtd_theme
   - pygments
   - pydot

pytensor/graph/op.py

@@ -356,6 +356,8 @@ class Op(MetaObject):
         grads
             The gradients with respect to each `Variable` in `inputs`.
 
+        References
+        ----------
         .. [1] Giles, Mike. 2008. “An Extended Collection of Matrix Derivative Results for Forward and Reverse Mode Automatic Differentiation.”
 
         """

pytensor/misc/pkl_utils.py

@@ -47,6 +47,8 @@ class StripPickler(Pickler):
     Example
     -------
 
+    ..code-block:: python
+
         fn_args = dict(inputs=inputs,
                        outputs=outputs,
                        updates=updates)
@@ -54,7 +56,6 @@ class StripPickler(Pickler):
         with open(dest_pkl, 'wb') as f:
             strip_pickler = StripPickler(f, protocol=-1)
             strip_pickler.dump(fn_args)
-
     """
 
     def __init__(self, file, protocol=0, extra_tag_to_remove=None):

pytensor/tensor/elemwise.py

@@ -1758,7 +1758,7 @@ def scalar_elemwise(*symbol, nfunc=None, nin=None, nout=None, symbolname=None):
             )
 
         if getattr(symbol, "__doc__"):
-            rval.__doc__ = symbol.__doc__ + "\n" + rval.__doc__
+            rval.__doc__ = symbol.__doc__ + "\n\n    " + rval.__doc__
 
         # for the meaning of this see the ./epydoc script
         # it makes epydoc display rval as if it were a function, not an object

pytensor/tensor/math.py

@@ -1442,18 +1442,18 @@ def betainc(a, b, x):
 
 @scalar_elemwise
 def real(z):
-    """Return real component of complex-valued tensor `z`"""
+    """Return real component of complex-valued tensor `z`."""
 
 
-_tensor_py_operators.real = property(real)
+_tensor_py_operators.real = property(real, doc=real.__doc__)
 
 
 @scalar_elemwise
 def imag(z):
-    """Return imaginary component of complex-valued tensor `z`"""
+    """Return imaginary component of complex-valued tensor `z`."""
 
 
-_tensor_py_operators.imag = property(imag)
+_tensor_py_operators.imag = property(imag, doc=imag.__doc__)
 
 
 @scalar_elemwise

pytensor/tensor/rewriting/math.py

-r"""Rewrites for the `Op`\s in `pytensor.tensor.math`."""
+r"""Rewrites for the `Op`\s in :mod:`pytensor.tensor.math`."""
 
 import itertools
 import operator

pytensor/tensor/var.py

@@ -654,13 +654,13 @@ class _tensor_py_operators:
     __rmatmul__ = __rdot__
 
     def sum(self, axis=None, dtype=None, keepdims=False, acc_dtype=None):
-        """See `pytensor.tensor.math.sum`."""
+        """See :func:`pytensor.tensor.math.sum`."""
         return at.math.sum(
             self, axis=axis, dtype=dtype, keepdims=keepdims, acc_dtype=acc_dtype
         )
 
     def prod(self, axis=None, dtype=None, keepdims=False, acc_dtype=None):
-        """See `pytensor.tensor.math.prod`."""
+        """See :func:`pytensor.tensor.math.prod`."""
         return at.math.prod(
             self, axis=axis, dtype=dtype, keepdims=keepdims, acc_dtype=acc_dtype
         )
@@ -681,73 +681,73 @@ class _tensor_py_operators:
             return y
 
     def mean(self, axis=None, dtype=None, keepdims=False, acc_dtype=None):
-        """See `pytensor.tensor.math.mean`."""
+        """See :func:`pytensor.tensor.math.mean`."""
         return at.math.mean(
             self, axis=axis, dtype=dtype, keepdims=keepdims, acc_dtype=acc_dtype
         )
 
     def var(self, axis=None, ddof=0, keepdims=False, corrected=False):
-        """See `pytensor.tensor.math.var`."""
+        """See :func:`pytensor.tensor.math.var`."""
         return at.math.var(
             self, axis=axis, ddof=ddof, keepdims=keepdims, corrected=corrected
         )
 
     def std(self, axis=None, ddof=0, keepdims=False, corrected=False):
-        """See `pytensor.tensor.math.std`."""
+        """See :func:`pytensor.tensor.math.std`."""
         return at.math.std(
             self, axis=axis, ddof=ddof, keepdims=keepdims, corrected=corrected
         )
 
     def min(self, axis=None, keepdims=False):
-        """See `pytensor.tensor.math.min`."""
+        """See :func:`pytensor.tensor.math.min`."""
         return at.math.min(self, axis, keepdims=keepdims)
 
     def max(self, axis=None, keepdims=False):
-        """See `pytensor.tensor.math.max`."""
+        """See :func:`pytensor.tensor.math.max`."""
         return at.math.max(self, axis, keepdims=keepdims)
 
     def argmin(self, axis=None, keepdims=False):
-        """See `pytensor.tensor.math.argmin`."""
+        """See :func:`pytensor.tensor.math.argmin`."""
         return at.math.argmin(self, axis, keepdims=keepdims)
 
     def argmax(self, axis=None, keepdims=False):
-        """See `pytensor.tensor.math.argmax`."""
+        """See :func:`pytensor.tensor.math.argmax`."""
         return at.math.argmax(self, axis, keepdims=keepdims)
 
     def nonzero(self, return_matrix=False):
-        """See `pytensor.tensor.basic.nonzero`."""
+        """See :func:`pytensor.tensor.basic.nonzero`."""
         return at.nonzero(self, return_matrix=return_matrix)
 
     def nonzero_values(self):
-        """See `pytensor.tensor.basic.nonzero_values`."""
+        """See :func:`pytensor.tensor.basic.nonzero_values`."""
         return at.nonzero_values(self)
 
     def sort(self, axis=-1, kind="quicksort", order=None):
-        """See `pytensor.tensor.sort.sort`."""
+        """See :func:`pytensor.tensor.sort.sort`."""
         return at.sort(self, axis, kind, order)
 
     def argsort(self, axis=-1, kind="quicksort", order=None):
-        """See `pytensor.tensor.sort.argsort`."""
+        """See :func:`pytensor.tensor.sort.argsort`."""
         from pytensor.tensor.sort import argsort
 
         return argsort(self, axis, kind, order)
 
     def clip(self, a_min, a_max):
-        "See `pytensor.tensor.math.clip`."
+        "See :func:`pytensor.tensor.math.clip`."
         return at.math.clip(self, a_min, a_max)
 
     def conj(self):
-        """See `pytensor.tensor.math.conj`."""
+        """See :func:`pytensor.tensor.math.conj`."""
         return at.math.conj(self)
 
     conjugate = conj
 
     def repeat(self, repeats, axis=None):
-        """See `pytensor.tensor.basic.repeat`."""
+        """See :func:`pytensor.tensor.basic.repeat`."""
         return at.extra_ops.repeat(self, repeats, axis)
 
     def round(self, mode=None):
-        """See `pytensor.tensor.math.round`."""
+        """See :func:`pytensor.tensor.math.round`."""
         return at.math.round(self, mode)
 
     def trace(self):
@@ -775,12 +775,12 @@ class _tensor_py_operators:
         return at.extra_ops.searchsorted(self, v, side, sorter)
 
     def ptp(self, axis=None):
-        """See `pytensor.tensor.math.ptp`."""
+        """See :func:`pytensor.tensor.math.ptp`."""
 
         return at.math.ptp(self, axis)
 
     def swapaxes(self, axis1, axis2):
-        """See `pytensor.tensor.basic.swapaxes`.
+        """See :func:`pytensor.tensor.basic.swapaxes`.
 
         If a matrix is provided with the right axes, its transpose
         will be returned.