Add cross reference in usage documentation

Author: AntoinePrv

docs/source/adaptor.rst

@@ -76,7 +76,7 @@ ownership of the array:
         // prints 0 2 (data is still available here)
     }
 
-However if you replace ``xt::no_ownership`` with ``xt::acquire_ownership``, the adaptor will take
+However if you replace :cpp:enumerator:`xt::no_ownership` with :cpp:enumerator:`xt::acquire_ownership`, the adaptor will take
 the ownership of the array, meaning it will be deleted when the adaptor is destroyed:
 
 .. code::
@@ -179,8 +179,8 @@ Adapting C++ smart pointers
 ---------------------------
 
 If you want to manage your data with shared or unique pointers, you can use the
-``adapt_smart_ptr`` function of xtensor. It will automatically increment the
-reference count of shared pointers upon creation, and decrement upon deletion.
+:cpp:func:`xt::adapt_smart_ptr` function of xtensor.
+It will automatically increment the reference count of shared pointers upon creation, and decrement upon deletion.
 
 .. code::
 

docs/source/api/container_index.rst

@@ -8,7 +8,7 @@ Containers and views
 ====================
 
 Containers are in-memory expressions that share a common implementation of most of the methods of the xexpression API.
-The final container classes (``xarray``, ``xtensor``) mainly implement constructors and value semantic, most of the
+The final container classes (:cpp:type:`xt::xarray`, :cpp:type:`xt::xtensor`) mainly implement constructors and value semantic, most of the
 xexpression API is actually implemented in ``xstrided_container`` and ``xcontainer``.
 
 .. toctree::

docs/source/api/expression_index.rst

@@ -7,7 +7,7 @@
 Expressions and semantic
 ========================
 
-``xexpression`` and the semantic classes contain all the methods required to perform evaluation and
+:cpp:type:`xt::xexpression` and the semantic classes contain all the methods required to perform evaluation and
 assignment of expressions. They define the computed assignment operators, the assignment methods for
 ``noalias`` and the downcast methods.
 

docs/source/api/xrandom.rst

@@ -11,84 +11,67 @@ Defined in ``xtensor/xrandom.hpp``
 
 .. warning:: xtensor uses a lazy generator for random numbers. You need to assign them or use ``eval`` to keep the generated values consistent.
 
-.. _random-get_default_random_engine-function-reference:
 .. doxygenfunction:: xt::random::get_default_random_engine
    :project: xtensor
 
-.. _random-seed-function-reference:
 .. doxygenfunction:: xt::random::seed
    :project: xtensor
 
-.. _random-rand-function-reference:
 .. doxygenfunction:: xt::random::rand(const S&, T, T, E&)
    :project: xtensor
 
-.. _random-randint-function-reference:
 .. doxygenfunction:: xt::random::randint(const S&, T, T, E&)
    :project: xtensor
 
-.. _random-randn-function-reference:
 .. doxygenfunction:: xt::random::randn(const S&, T, T, E&)
    :project: xtensor
 
-.. _random-binomial-function-reference:
 .. doxygenfunction:: xt::random::binomial(const S&, T, D, E&)
    :project: xtensor
 
-.. _random-geometric-function-reference:
 .. doxygenfunction:: xt::random::geometric(const S&, D, E&)
    :project: xtensor
 
-.. _random-negative_binomial-function-reference:
 .. doxygenfunction:: xt::random::negative_binomial(const S&, T, D, E&)
    :project: xtensor
 
-.. _random-poisson-function-reference:
 .. doxygenfunction:: xt::random::poisson(const S&, D, E&)
    :project: xtensor
 
-.. _random-exponential-function-reference:
 .. doxygenfunction:: xt::random::exponential(const S&, T, E&)
    :project: xtensor
 
-.. _random-gamma-function-reference:
 .. doxygenfunction:: xt::random::gamma(const S&, T, T, E&)
    :project: xtensor
 
-.. _random-weibull-function-reference:
 .. doxygenfunction:: xt::random::weibull(const S&, T, T, E&)
    :project: xtensor
 
-.. _random-extreme_value-function-reference:
 .. doxygenfunction:: xt::random::extreme_value(const S&, T, T, E&)
    :project: xtensor
 
-.. _random-lognormal-function-reference:
 .. doxygenfunction:: xt::random::lognormal(const S&, T, T, E&)
    :project: xtensor
 
-.. _random-cauchy-function-reference:
+.. doxygenfunction:: xt::random::chi_squared(const S&, T, E&)
+   :project: xtensor
+
 .. doxygenfunction:: xt::random::cauchy(const S&, T, T, E&)
    :project: xtensor
 
-.. _random-fisher_f-function-reference:
 .. doxygenfunction:: xt::random::fisher_f(const S&, T, T, E&)
    :project: xtensor
 
-.. _random-student_t-function-reference:
 .. doxygenfunction:: xt::random::student_t(const S&, T, E&)
    :project: xtensor
 
-.. _random-choice-function-reference:
 .. doxygenfunction:: xt::random::choice(const xexpression<T>&, std::size_t, bool, E&)
    :project: xtensor
 .. doxygenfunction:: xt::random::choice(const xexpression<T>&, std::size_t, const xexpression<W>&, bool, E&)
    :project: xtensor
 
-.. _random-shuffle-function-reference:
 .. doxygenfunction:: xt::random::shuffle
    :project: xtensor
 
-.. _random-permutation-function-reference:
 .. doxygenfunction:: xt::random::permutation(T, E&)
    :project: xtensor

docs/source/build-options.rst

@@ -12,15 +12,15 @@ Build and configuration
 Configuration
 -------------
 
-``xtensor`` can be configured via macros which must be defined *before* including
+`xtensor` can be configured via macros which must be defined *before* including
 any of its headers. This can be achieved the following ways:
 
 - either define them in the CMakeLists of your project, with ``target_compile_definitions``
   cmake command.
 - or create a header where you define all the macros you want and then include the headers you
-  need. Then include this header whenever you need ``xtensor`` in your project.
+  need. Then include this header whenever you need `xtensor` in your project.
 
-The following macros are already defined in ``xtensor`` but can be overwritten:
+The following macros are already defined in `xtensor` but can be overwritten:
 
 - ``XTENSOR_DEFAULT_DATA_CONTAINER(T, A)``: defines the type used as the default data container for tensors and arrays. ``T``
   is the ``value_type`` of the container and ``A`` its ``allocator_type``.
@@ -35,8 +35,8 @@ The following macros are already defined in ``xtensor`` but can be overwritten:
 
 The following macros are helpers for debugging, they are not defined by default:
 
-- ``XTENSOR_ENABLE_ASSERT``: enables assertions in xtensor, such as bound check.
-- ``XTENSOR_ENABLE_CHECK_DIMENSION``: enables the dimensions check in ``xtensor``. Note that this option should not be turned
+- ``XTENSOR_ENABLE_ASSERT``: enables assertions in `xtensor`, such as bound check.
+- ``XTENSOR_ENABLE_CHECK_DIMENSION``: enables the dimensions check in `xtensor`. Note that this option should not be turned
   on if you expect ``operator()`` to perform broadcasting.
 
 .. _external-dependencies:
@@ -47,14 +47,14 @@ External dependencies
 The last group of macros is for using external libraries to achieve maximum performance (see next section for additional
 requirements):
 
-- ``XTENSOR_USE_XSIMD``: enables SIMD acceleration in ``xtensor``. This requires that you have xsimd_ installed
+- ``XTENSOR_USE_XSIMD``: enables SIMD acceleration in `xtensor`. This requires that you have xsimd_ installed
   on your system.
 - ``XTENSOR_USE_TBB``: enables parallel assignment loop. This requires that you have tbb_ installed
   on your system.
 - ``XTENSOR_DISABLE_EXCEPTIONS``: disables c++ exceptions.
 - ``XTENSOR_USE_OPENMP``: enables parallel assignment loop using OpenMP. This requires that OpenMP is available on your system.
 
-Defining these macros in the CMakeLists of your project before searching for ``xtensor`` will trigger automatic finding
+Defining these macros in the CMakeLists of your project before searching for `xtensor` will trigger automatic finding
 of dependencies, so you don't have to include the ``find_package(xsimd)`` and ``find_package(TBB)`` commands in your
 CMakeLists:
 

docs/source/builder.rst

@@ -14,68 +14,70 @@ Values are computed upon request.
 Ones and zeros
 --------------
 
-- ``zeros(shape)``: generates an expression containing zeros of the specified shape.
-- ``ones(shape)``: generates an expression containing ones of the specified shape.
-- ``eye(shape, k=0)``: generates an expression of the specified shape, with ones on the k-th diagonal.
-- ``eye(n, k = 0)``: generates an expression of shape ``(n, n)`` with ones on the k-th diagonal.
+- :cpp:func:`xt::zeros(shape) <xt::zeros>`: generates an expression containing zeros of the specified shape.
+- :cpp:func:`xt::ones(shape) <xt::ones>`: generates an expression containing ones of the specified shape.
+- :cpp:func:`xt::eye(shape, k=0) <xt::eye>`: generates an expression of the specified shape, with ones on the k-th diagonal.
+- :cpp:func:`xt::eye(n, k = 0) <xt::eye>`: generates an expression of shape ``(n, n)`` with ones on the k-th diagonal.
 
 Numerical ranges
 ----------------
 
-- ``arange(start=0, stop, step=1)``: generates numbers evenly spaced within given half-open interval.
-- ``linspace(start, stop, num_samples)``: generates num_samples evenly spaced numbers over given interval.
-- ``logspace(start, stop, num_samples)``: generates num_samples evenly spaced on a log scale over given interval
+- :cpp:func:`xt::arange(start=0, stop, step=1) <xt::arange>`: generates numbers evenly spaced within given half-open interval.
+- :cpp:func:`xt::linspace(start, stop, num_samples) <xt::linspace>`: generates num_samples evenly spaced numbers over given interval.
+- :cpp:func:`xt::logspace(start, stop, num_samples) <xt::logspace>`: generates num_samples evenly spaced on a log scale over given interval
 
 Joining expressions
 -------------------
 
-- ``concatenate(tuple, axis=0)``: concatenates a list of expressions along the given axis.
-- ``stack(tuple, axis=0)``: stacks a list of expressions along the given axis.
-- ``hstack(tuple)``: stacks expressions in sequence horizontally (i.e. column-wise).
-- ``vstack(tuple)``: stacks expressions in sequence vertically (i.e. row wise).
+- :cpp:func:`xt::concatenate(tuple, axis=0) <xt::concatenate>`: concatenates a list of expressions along the given axis.
+- :cpp:func:`xt::stack(tuple, axis=0) <xt::stack>`: stacks a list of expressions along the given axis.
+- :cpp:func:`xt::hstack(tuple) <xt::hstack>`: stacks expressions in sequence horizontally (i.e. column-wise).
+- :cpp:func:`xt::vstack(tuple) <xt::vstack>`: stacks expressions in sequence vertically (i.e. row wise).
 
 Random distributions
 --------------------
 
-.. warning:: xtensor uses a lazy generator for random numbers. You need to assign them or use ``eval`` to keep the generated values consistent.
-
-- ``rand(shape, lower, upper)``: generates an expression of the specified shape, containing uniformly
-  distributed random numbers in the half-open interval [lower, upper).
-- ``randint(shape, lower, upper)``: generates an expression of the specified shape, containing uniformly
-  distributed random integers in the half-open interval [lower, upper).
-- ``randn(shape, mean, std_dev)``: generates an expression of the specified shape, containing numbers
-  sampled from the Normal random number distribution.
-- ``binomial(shape, trials, prob)``: generates an expression of the specified shape, containing numbers
-  sampled from the binomial random number distribution.
-- ``geometric(shape, prob)``: generates an expression of the specified shape, containing numbers
-  sampled from the geometric random number distribution.
-- ``negative_binomial(shape, k, prob)``: generates an expression of the specified shape, containing numbers
-  sampled from the negative binomial random number distribution.
-- ``poisson(shape, rate)``: generates an expression of the specified shape, containing numbers
-  sampled from the Poisson random number distribution.
-- ``exponential(shape, rate)``: generates an expression of the specified shape, containing numbers
-  sampled from the exponential random number distribution.
-- ``gamma(shape, alpha, beta)``: generates an expression of the specified shape, containing numbers
-  sampled from the gamma random number distribution.
-- ``weibull(shape, a, b)``: generates an expression of the specified shape, containing numbers
-  sampled from the Weibull random number distribution.
-- ``extreme_value(shape, a, b)``: generates an expression of the specified shape, containing numbers
-  sampled from the extreme value random number distribution.
-- ``lognormal(shape, a, b)``: generates an expression of the specified shape, containing numbers
-  sampled from the Log-Normal random number distribution.
-- ``chi_squared(shape, a, b)``: generates an expression of the specified shape, containing numbers
-  sampled from the chi-squared random number distribution.
-- ``cauchy(shape, a, b)``: generates an expression of the specified shape, containing numbers
-  sampled from the Cauchy random number distribution.
-- ``fisher_f(shape, m, n)``: generates an expression of the specified shape, containing numbers
-  sampled from the Fisher-f random number distribution.
-- ``student_t(shape, n)``: generates an expression of the specified shape, containing numbers
-  sampled from the Student-t random number distribution.
+.. warning:: xtensor uses a lazy generator for random numbers.
+   You need to assign them or use :cpp:func:`xt::eval` to keep the generated values consistent.
+
+- :cpp:func:`xt::random::rand(shape, lower, upper) <xt::random::rand>`: generates an expression of the specified
+  shape, containing uniformly distributed random numbers in the half-open interval [lower, upper).
+- :cpp:func:`xt::random::randint(shape, lower, upper) <xt::random::randint>`: generates an expression of the specified
+  shape, containing uniformly distributed random integers in the half-open interval [lower, upper).
+- :cpp:func:`xt::random::randn(shape, mean, std_dev) <xt::random::randn>`: generates an expression of the specified
+  shape, containing numbers sampled from the Normal random number distribution.
+- :cpp:func:`xt::random::binomial(shape, trials, prob) <xt::random::binomial>`: generates an expression of the specified
+  shape, containing numbers sampled from the binomial random number distribution.
+- :cpp:func:`xt::random::geometric(shape, prob) <xt::random::geometric>`: generates an expression of the specified shape,
+  containing numbers sampled from the geometric random number distribution.
+- :cpp:func:`xt::random::negative_binomial(shape, k, prob) <xt::random::negative_binomial>`: generates an expression
+  of the specified shape, containing numbers sampled from the negative binomial random number distribution.
+- :cpp:func:`xt::random::poisson(shape, rate) <xt::random::poisson>`: generates an expression of the specified shape,
+  containing numbers sampled from the Poisson random number distribution.
+- :cpp:func:`xt::random::exponential(shape, rate) <xt::random::exponential>`: generates an expression of the specified
+  shape, containing numbers sampled from the exponential random number distribution.
+- :cpp:func:`xt::random::gamma(shape, alpha, beta) <xt::random::gamma>`: generates an expression of the specified shape,
+  containing numbers sampled from the gamma random number distribution.
+- :cpp:func:`xt::random::weibull(shape, a, b) <xt::random::weibull>`: generates an expression of the specified shape,
+  containing numbers sampled from the Weibull random number distribution.
+- :cpp:func:`xt::random::extreme_value(shape, a, b) <xt::random::extreme_value>`: generates an expression of the
+  specified shape, containing numbers sampled from the extreme value random number distribution.
+- :cpp:func:`xt::random::lognormal(shape, a, b) <xt::random::lognormal>`: generates an expression of the specified
+  shape, containing numbers sampled from the Log-Normal random number distribution.
+- :cpp:func:`xt::random::chi_squared(shape, a, b) <xt::random::chi_squared>`: generates an expression of the specified
+  shape, containing numbers sampled from the chi-squared random number distribution.
+- :cpp:func:`xt::random::cauchy(shape, a, b) <xt::random::cauchy>`: generates an expression of the specified shape,
+  containing numbers sampled from the Cauchy random number distribution.
+- :cpp:func:`xt::random::fisher_f(shape, m, n) <xt::random::fisher_f>`: generates an expression of the specified shape,
+  containing numbers sampled from the Fisher-f random number distribution.
+- :cpp:func:`xt::random::student_t(shape, n) <xt::random::student_t>`: generates an expression of the specified shape,
+  containing numbers sampled from the Student-t random number distribution.
 
 Meshes
 ------
 
-- ``meshgrid(x1, x2,...)```: generates N-D coordinate expressions given one-dimensional coordinate arrays ``x1``, ``x2``...
+- :cpp:func:`xt::meshgrid(x1, x2,...) <xt::meshgrid>`: generates N-D coordinate expressions given
+  one-dimensional coordinate arrays ``x1``, ``x2``...
   If specified vectors have lengths ``Ni = len(xi)``, meshgrid returns ``(N1, N2, N3,..., Nn)``-shaped arrays, with the elements
   of xi repeated to fill the matrix along the first dimension for x1, the second for x2 and so on.
 

docs/source/closure-semantics.rst

@@ -12,8 +12,8 @@ Closure semantics
 The ``xtensor`` library is a tensor expression library implementing numpy-style broadcasting and universal functions but in a lazy fashion.
 
 If ``x`` and ``y`` are two tensor expressions with compatible shapes, the result of ``x + y`` is not a tensor but an expression that does
-not hold any value. Values of ``x + y`` are computed upon access or when the result is assigned to a container such as ``xt::xtensor`` or
-``xt::xarray``. The same holds for most functions in xtensor, views, broadcasting views, etc.
+not hold any value. Values of ``x + y`` are computed upon access or when the result is assigned to a container such as :cpp:type:`xt::xtensor` or
+:cpp:type:`xt::xarray`. The same holds for most functions in xtensor, views, broadcasting views, etc.
 
 In order to be able to perform the differed computation of ``x + y``, the returned expression must hold references, const references or
 copies of the members ``x`` and ``y``, depending on how arguments were passed to ``operator+``. The actual types held by the expressions

docs/source/conf.py

@@ -46,4 +46,5 @@ def setup(app):
     "numpy": ("https://numpy.org/doc/stable/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
     "xtensor-blas": ("https://xtensor-blas.readthedocs.io/en/stable", None),
+    "xtl": ("https://xtl.readthedocs.io/en/stable", None),
 }