Small improvements to docs API

.github/workflows/rtd-link-preview.yml

@@ -0,0 +1,16 @@
+name: Read the Docs Pull Request Preview
+on:
+  pull_request_target:
+    types:
+      - opened
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "pytensor"

doc/library/graph/graph.rst

@@ -4,12 +4,5 @@
 :mod:`graph` -- Interface for the PyTensor graph
 ================================================
 
----------
-Reference
----------
-
 .. automodule:: pytensor.graph.basic
-   :platform: Unix, Windows
-   :synopsis: Interface for types of symbolic variables
    :members:
-.. moduleauthor:: LISA

doc/library/graph/index.rst

@@ -1,20 +1,20 @@
 
 .. _libdoc_graph:
 
-================================================
-:mod:`graph` -- Theano Internals [doc TODO]
-================================================
+========================================
+:mod:`graph` -- PyTensor Graph Internals
+========================================
 
 .. module:: graph
-   :platform: Unix, Windows
-   :synopsis: Theano Internals
+
 .. moduleauthor:: LISA
 
 .. toctree::
     :maxdepth: 1
 
     graph
     fgraph
+    replace
     features
     op
     type

doc/library/graph/op.rst

@@ -1,12 +1,8 @@
-
 .. _libdoc_graph_op:
 
-==============================================================
-:mod:`graph` -- Objects and functions for computational graphs
-==============================================================
+===========================================
+:mod:`op` -- Objects that define operations
+===========================================
 
 .. automodule:: pytensor.graph.op
-   :platform: Unix, Windows
-   :synopsis: Interface for types of symbolic variables
-   :members:
-.. moduleauthor:: LISA
+   :members:

doc/library/graph/replace.rst

@@ -0,0 +1,8 @@
+.. _libdoc_graph_replace:
+
+==================================================
+:mod:`replace` -- High level graph transformations
+==================================================
+
+.. automodule:: pytensor.graph.replace
+   :members:

doc/library/tensor/functional.rst

@@ -0,0 +1,2 @@
+.. automodule:: pytensor.tensor.functional
+    :members: vectorize

doc/library/tensor/index.rst

@@ -1,17 +1,18 @@
 .. _libdoc_tensor:
 
-==================================================
-:mod:`tensor`  -- Types and Ops for Symbolic numpy
-==================================================
+===============================================
+:mod:`tensor`  -- Tensor operations in PyTensor
+===============================================
 
 .. module:: tensor
-   :platform: Unix, Windows
-   :synopsis: symbolic types and operations for n-dimensional arrays.
-.. moduleauthor:: LISA
 
-Theano's strength is in expressing symbolic calculations involving tensors.
-There are many types of symbolic expressions for tensors.
-They are grouped into the following sections:
+PyTensor's strength is in expressing symbolic calculations involving tensors.
+
+PyTensor tries to emulate the numpy interface as much as possible in the tensor module.
+This means that once TensorVariables are created, it should be possibly to define
+symbolic expressions using calls that look just like numpy calls, such as
+`pt.exp(x).transpose(0, 1)[:, None]`
+
 
 
 .. toctree::
@@ -29,3 +30,4 @@ They are grouped into the following sections:
     conv
     math_opt
     basic_opt
+    functional

doc/library/tensor/random/distributions.rst

@@ -0,0 +1,8 @@
+.. _libdoc_tensor_random_distributions:
+
+Distributions
+=============
+
+.. automodule:: pytensor.tensor.random.basic
+   :members:
+   :special-members: __call__

doc/library/tensor/random/index.rst

@@ -1,21 +1,89 @@
-.. _libdoc_tensor_random:
+
+.. _libdoc_tensor_random_basic:
 
 =============================================
-:mod:`random` -- Low-level random numbers
+:mod:`random` -- Random number functionality
 =============================================
 
-Low-level random numbers
-------------------------
+.. module:: pytensor.tensor.random
+   :synopsis: symbolic random variables
+
 
 The :mod:`pytensor.tensor.random` module provides random-number drawing functionality
 that closely resembles the :mod:`numpy.random` module.
 
-.. toctree::
-    :maxdepth: 2
 
-    basic
-    utils
+High-level API
+==============
+
+PyTensor assigns NumPy RNG states (i.e. `Generator` objects) to
+each `RandomVariable`.  The combination of an RNG state, a specific
+`RandomVariable` type (e.g. `NormalRV`), and a set of distribution parameters
+uniquely defines the `RandomVariable` instances in a graph.
+
+This means that a "stream" of distinct RNG states is required in order to
+produce distinct random variables of the same kind. `RandomStream` provides a
+means of generating distinct random variables in a fully reproducible way.
+
+`RandomStream` is also designed to produce simpler graphs and work with more
+sophisticated `Op`\s like `Scan`, which makes it a user-friendly random variable
+interface in PyTensor.
+
+For an example of how to use random numbers, see :ref:`Using Random Numbers <using_random_numbers>`.
+
+
+.. class:: RandomStream()
+
+    This is a symbolic stand-in for `numpy.random.Generator`.
+
+    .. method:: updates()
+
+        :returns: a list of all the (state, new_state) update pairs for the
+          random variables created by this object
+
+        This can be a convenient shortcut to enumerating all the random
+        variables in a large graph in the ``update`` argument to
+        `pytensor.function`.
+
+    .. method:: seed(meta_seed)
+
+        `meta_seed` will be used to seed a temporary random number generator,
+        that will in turn generate seeds for all random variables
+        created by this object (via `gen`).
+
+        :returns: None
+
+    .. method:: gen(op, *args, **kwargs)
+
+        Return the random variable from ``op(*args, **kwargs)``.
+
+        This function also adds the returned variable to an internal list so
+        that it can be seeded later by a call to `seed`.
+
+    .. method:: uniform, normal, binomial, multinomial, random_integers, ...
+
+        See :ref: Available distributions `<_libdoc_tensor_random_distributions>`.
+
+
+   .. testcode:: constructors
+
+      from pytensor.tensor.random.utils import RandomStream
+
+      rng = RandomStream()
+      sample = rng.normal(0, 1, size=(2, 2))
+
+      fn = pytensor.function([], sample)
+      print(fn(), fn())  # different numbers due to default updates
+
+
+Low-level objects
+=================
+
+.. automodule:: pytensor.tensor.random.op
+   :members: RandomVariable, default_rng
 
+..automodule:: pytensor.tensor.random.type
+   :members: RandomType, RandomGeneratorType, random_generator_type
 
-.. automodule:: pytensor.tensor.random.basic
-    :members:
+.. automodule:: pytensor.tensor.random.var
+    :members: RandomGeneratorSharedVariable