Merge pull request #1256 from kohr-h/doc_fixes

DOC: various fixes (refs, format etc.) to the docs

doc/Makefile

@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = build
 SOURCEDIR     = source
 
 # User-friendly check for sphinx-build

doc/source/dev/dev.rst

@@ -21,7 +21,7 @@ In order to properly follow the ODL style, we recommend that you read the :ref:`
 .. note::
 
     This documentation is intended for contributions to core ODL.
-    For experimental contributions or extensions that would be too specialized for core ODL, we have the `odl/contrib <https://github.com/odlgroup/odl/tree/master/odl/contrib`_ directory that offers a "fast lane" with a more relaxed code quality and consistency policy.
+    For experimental contributions or extensions that would be too specialized for core ODL, we have the `odl/contrib <https://github.com/odlgroup/odl/tree/master/odl/contrib>`_ directory that offers a "fast lane" with a more relaxed code quality and consistency policy.
 
 
 Contents

doc/source/dev/testing.rst

@@ -4,27 +4,27 @@
 Testing in ODL
 ##############
 
-ODL is tested using pytest_ and has four main types of tests and verification measures that are supposed to test the code in different ways. 
-These are listed below along with the command to run them.
+ODL tests are run using pytest_, and there are several types:
+
 
 ==============  =========================  =======
 Name            Command                    Description
 ==============  =========================  =======
-Unit tests      `pytest`                   Test "micro-features" of the code, like testing that each parameter combination works, that the correct exceptions are raised, that the code works correctly in corner cases and with a wide range of input.
-Large-scale     `pytest --largescale`      Verify that the functionality works well in more complicated and realistic conditions with potentially large input data and longer running times.
-Doctests        `pytest`                   Run the code in the docstring examples and check the output against the documented ones. Mainly intended to validate the examples.
-Examples        `pytest --examples`        Run all examples in the `examples`_ folder. These are copy-paste friendly examples on how to use a function in a more complete context.
-Documentation   `pytest --documentation`   Run all examples in the documentation. Examples are occasionally used in the documentation to demonstrate a concept. Here we only check that the code is valid and actually runs.
+Unit tests      ``pytest``                 Test "micro-features" of the code
+Large-scale     ``pytest --largescale``    Unit tests with large inputs and more cases
+Doctests        ``pytest``                 Validate usage examples in docstrings
+Examples        ``pytest --examples``      Run all examples in the `examples`_ folder
+Documentation   ``pytest --doctest-doc``   Run the doctest examples in the Sphinx documentation
 ==============  =========================  =======
 
 Unit tests
 ~~~~~~~~~~
-All unit tests in ODL are contained in the `tests`_ folder, where each ODL sub-package has a test file on its own. 
-Any major ODL functionality should have unit tests covering all of the use cases that are implied in the documentation. 
-In addition to this, the tests should be quick to run, preferably at most a few milliseconds per test. 
+All unit tests in ODL are contained in the `test`_ folder, where each sub-package has a test file on its own.
+Any major ODL functionality should have unit tests covering all of the use cases that are implied in the documentation.
+In addition to this, the tests should be quick to run, preferably at most a few milliseconds per test.
 If the test suite takes too long to run, users and developers won't run them as often as necessary to make sure that they didn't break any functionality.
 
-A short example of testing a function is given below. 
+A short example of testing a function is given below.
 For more information consult the `pytest`_ documentation and look at existing tests in the `test`_ folder.
 
 .. code:: python
@@ -75,7 +75,7 @@ It may also be the case that some functions accept a very large number of possib
 
 Doctests
 ~~~~~~~~
-Doctests are the simplest type of test used in ODL, and are snippets of code that document the usage of functions and classes and can be run as small tests at the same time. 
+Doctests are the simplest type of test used in ODL, and are snippets of code that document the usage of functions and classes and can be run as small tests at the same time.
 They can be included by using the Examples header in an usual docstring, as shown below:
 
 .. code:: python
@@ -108,12 +108,12 @@ All ODL source files should also contain the lines:
         from odl.util.testutils import run_doctests
         run_doctests()
 
-which mean that if a ODL source file is executed in isolation, all the doctests in the file are run. 
+which mean that if a ODL source file is executed in isolation, all the doctests in the file are run.
 This can be useful during development in order to quickly see if some functionality works as expected.
 
 Examples
 ~~~~~~~~
-Examples, while not technically tests in the traditional sense, still constitute a part of the test framework for ODL by showing how different parts of ODL work together and by ensuring that functions that depend on each other work as expected. 
+Examples, while not technically tests in the traditional sense, still constitute a part of the test framework for ODL by showing how different parts of ODL work together and by ensuring that functions that depend on each other work as expected.
 The main purpose of the examples is however to show ODL from a users perspective and particular care should be taken to keep them readable and working since this is often the first thing users see when they start using ODL.
 
 It is even possible to run all examples as part of the test suite by running ``pytest --examples``, but be aware that this requires all ODL dependencies to be installed and that plotting windows can be opened during execution.
@@ -123,4 +123,4 @@ Consult the `examples`_ directory for an impression of the style in which ODL ex
 .. _doctest: https://docs.python.org/library/doctest.html
 .. _pytest: http://doc.pytest.org/en/latest/
 .. _examples: https://github.com/odlgroup/odl/tree/master/examples
-.. _test: https://github.com/odlgroup/odl/tree/master/odl/test
+.. _test: https://github.com/odlgroup/odl/tree/master/odl/test

doc/source/getting_started/first_steps.rst

@@ -109,7 +109,7 @@ The adjoint is a generalization of the transpose of a matrix and defined as the
     \langle Ax, y \rangle = \langle x, A^*y \rangle
 
 where :math:`\langle x, y \rangle` is the inner product.
-It is implemented in odl as `Operator.adjoint`.
+It is implemented in odl as `~odl.operator.operator.Operator.adjoint`.
 Luckily, the convolution operator is self adjoint if the kernel is symmetric, so we can add:
 
 .. code-block:: python
@@ -220,7 +220,7 @@ Consulting the `douglas_rachford_pd` documentation we see that it solves problem
     \min_x f(x) + \sum_{i=1}^n g_i(L_i x),
 
 where :math:`f`, :math:`g_i` are convex functions, :math:`L_i` are linear `Operator`'s.
-By identification, we see that the above problem can be written in this form if we let math:`f` be the indicator function on :math:`[0, 1]`,
+By identification, we see that the above problem can be written in this form if we let :math:`f` be the indicator function on :math:`[0, 1]`,
 :math:`g_1` be the squared l2 distance :math:`\| \cdot - g\|_2^2`,
 :math:`g_2` be the norm :math:`\| \cdot \|_1`,
 :math:`L_1` be the convolution operator and :math:`L_2` be the gradient operator.

doc/source/getting_started/getting_started.rst

@@ -14,4 +14,8 @@ Here you can find an overview over the basics of ODL, a step-by-step installatio
 
    about_odl
    installing
+   installing_conda
+   installing_pip
+   installing_source
+   installing_extensions
    first_steps

doc/source/getting_started/installing.rst

@@ -6,6 +6,9 @@ Installing ODL
 
 This guide will go through all steps necessary for a full ODL installation, starting from nothing more than a working operating system (Linux, MacOS or Windows).
 
+
+.. _installing_odl__tldr:
+
 TL;DR
 =====
 If you already have a working python environment, ODL and some basic dependencies can be installed using either `pip`_:
@@ -26,6 +29,9 @@ After installation, the installation can be verified by running the tests:
 
     $ python -c "import odl; odl.test()"
 
+
+.. _installing_odl__introduction:
+
 Introduction
 ============
 
@@ -37,6 +43,9 @@ For a working installation you should perform the following steps:
 3. (optional) Install extensions for more functionality
 4. (optional) Run the tests
 
+
+.. _installing_odl__consider_anaconda:
+
 Consider using Anaconda
 =======================
 We currently recommend to use `Anaconda`_ on all platforms since it offers the best out-of-the-box installation and run-time experience.
@@ -49,20 +58,29 @@ We will provide instructions for this alternative.
 Another possibility is to use `virtualenv`_, which can be seen as a predecessor to Anaconda.
 Following the ``pip`` installation instructions in a ``virtualenv`` without the ``--user`` option works very well in our experience, but we do not provide explicit instructions for this variant.
 
+
+.. _installing_odl__python_version:
+
 Which Python version to use?
 ============================
 Any modern Python distribution supporting `NumPy`_ and `SciPy`_ should work for the core library, but some extensions require CPython (the standard Python distribution).
 
 ODL fully supports both Python 2 and Python 3.
-If you choose to use your system Python interpreter (the "pip install as user" variant), it may be a good idea to stick with the default one, i.e. the one invoked by ``python``.
+If you choose to use your system Python interpreter (the "pip install as user" variant), it may be a good idea to stick with the default one, i.e. the one invoked by the ``python`` command on the command line.
 Otherwise, we recommend using Python 3, since Python 2 support will be discontinued in 2020.
 
+
+.. _installing_odl__development_environment:
+
 Development environment
 =======================
 Since ODL is object-oriented, using an Integrated Development Environment (IDE) is recommended, but not required.
 The most popular ones are `Spyder`_ which works on all major platforms and can be installed through both ``conda`` and ``pip``, and `PyCharm`_ which can be integrated with any text editor of your choice, such as Emacs or Vim.
 
-In depth guides
+
+.. _installing_odl__in_depth_guides:
+
+In-depth guides
 ===============
 If you are a new user or need more a detailed installation guide, we provide support for the following installation methods:
 
@@ -72,6 +90,9 @@ If you are a new user or need more a detailed installation guide, we provide sup
 
 To further extend ODL capability, a :ref:`large set of extensions<installing_odl_extensions>` can also be installed.
 
+
+.. _installing_odl__issues:
+
 Issues
 ======
 If you have any problems during installation, consult the help in the :ref:`FAQ <FAQ>`.

doc/source/getting_started/installing_conda.rst

@@ -8,6 +8,9 @@ Anaconda is a binary distribution package that allows user to install pre-compil
 It works on all platforms and is the recommended way of installing ODL as a user.
 If you already have anaconda installed, you can go directly to `Installing ODL and its dependencies`_, otherwise you need to begin by installing anaconda.
 
+
+.. _installing_odl_conda__tldr:
+
 TL;DR
 =====
 Instructions for the impatient:
@@ -22,7 +25,7 @@ Instructions for the impatient:
 - Activate the conda enviroment and start working!
 
 
-.. _installing_anaconda:
+.. _installing_odl_conda__installing_anaconda:
 
 Installing Anaconda
 ===================
@@ -58,7 +61,7 @@ If you want to exit later on, run ``source deactivate`` (Linux/MacOS) or ``deact
 See the `Managing conda environments`_ documentation for further information.
 
 .. note::
-    If you want to use `Spyder`_ as integrated development environment (IDE, see `Development enviroment`_) on Linux or MacOS, you should also install it in the new conda environment and run it from there.
+    If you want to use `Spyder`_ as integrated development environment (IDE, see :ref:`installing_odl__development_environment`) on Linux or MacOS, you should also install it in the new conda environment and run it from there.
     Otherwise, Spyder may not able to use the packages in the conda environment:
 
     .. code-block:: bash
@@ -90,7 +93,8 @@ Install ODL and all its (minimal) dependencies in a ``conda`` environment of you
 
     After that, ``conda install odl`` and ``conda update odl`` work without the ``-c`` option.
 
-.. _installing_odl_conda_extensions:
+
+.. _installing_odl_conda__extensions:
 
 Extra dependencies
 ------------------
@@ -133,7 +137,7 @@ further instructions.
 
     $ conda install -c astra-toolbox astra-toolbox
 
-  If this doesn't work, or if you want a more recent version, check out the :ref:`ASTRA for X-ray tomography` section below.
+  If this doesn't work, or if you want a more recent version, see `the ASTRA GitHub page <https://github.com/astra-toolbox/astra-toolbox>`_.
 
 - Bindings to the `ProxImaL`_ convex optimization package, an extension of `CVXPY`_:
 
@@ -143,6 +147,9 @@ further instructions.
 
 More information can be found in :ref:`installing_odl_extensions`.
 
+
+.. _installing_odl_conda__running tests:
+
 Running the tests
 =================
 Unit tests in ODL are based on `pytest`_.

doc/source/getting_started/installing_extensions.rst

@@ -1,12 +1,21 @@
 .. _installing_odl_extensions:
 
+#########################
+Installing ODL extensions
+#########################
+
+
+.. _installing_odl_extensions__compiled:
+
 Compiled extensions
 ===================
 There are several compiled extensions to ODL.
 Some of them can be installed using ``conda`` or `pip`_, others require manual compilation.
 This section assumes that you have a working installation of python and ODL.
 
 
+.. _installing_odl_extensions__astra:
+
 ASTRA for X-ray tomography
 ==========================
 To calculate fast forward and backward projections for image reconstruction in X-ray tomography, install the `ASTRA tomography toolbox <https://github.com/astra-toolbox/astra-toolbox>`_.
@@ -29,6 +38,12 @@ Support for STIR is currently very limited.
 
 CUDA backend for linear arrays
 ==============================
+
+.. warning::
+    This plugin is dysfunctional with ODL master since the API change introduced by :pull:`1088`.
+    It can be used with older versions of ODL (e.g., with the current release).
+    The plugin will be replaced by CuPy in short (:pull:`1231`).
+
 The `odlcuda`_ backend for fast array calculations on CUDA requires the `CUDA toolkit`_ (on Linux: use your distro package manager) and a CUDA capable graphics card with compute capability of at least 3.0.
 Search `this table <https://en.wikipedia.org/wiki/CUDA#GPUs_supported>`_ for your model.
 
@@ -46,7 +61,7 @@ For both, first clone the ``odlcuda`` GitHub repository and enter the new direct
 
    This is the simpler option and should work on any Linux or MacOS system (we currently have no Windows build recipe, sorry).
 
-   To build the conda recipe, you should be **in the root conda environment** (see :ref:`installing_anaconda` for details) and in the top-level directory of your ``odlcuda`` clone.
+   To build the conda recipe, you should be **in the root conda environment** (see :ref:`installing_odl_conda__installing_anaconda` for details) and in the top-level directory of your ``odlcuda`` clone.
    You also need the ``conda-build`` package, which is installed by
 
    .. code-block:: bash

doc/source/getting_started/installing_pip.rst

@@ -3,6 +3,7 @@
 ========================
 Installing ODL using pip
 ========================
+
 `pip`_ is a package manager that works on all major platforms and allows user to install python packages in a very simple manner.
 If you already have python and pip installed, you can go directly to `Installing ODL and its dependencies`_, otherwise you need to begin by installing python and pip.
 
@@ -11,6 +12,9 @@ If you already have python and pip installed, you can go directly to `Installing
     Correctly installing ODL's dependencies on Windows, especially `Numpy`_ and other compiled dependencies, can be quite a hassle, and we therefore discourage this variant.
     You should really consider :ref:`using Anaconda instead <installing_odl_conda>`.
 
+
+.. _installing_odl_pip__tldr:
+
 TL;DR
 =====
 Instructions for the impatient:
@@ -22,6 +26,9 @@ Instructions for the impatient:
 
     $ pip install odl[show,pywavelets,scikit,proximal,testing]
 
+
+.. _installing_odl_pip__python:
+
 Installing a Python interpreter
 ===============================
 Open a terminal and type ``python`` + Enter.
@@ -42,6 +49,8 @@ Python installers can be downloaded from `this link <https://www.python.org/down
 Pick the latest release for your favorite version (2 or 3).
 
 
+.. _installing_odl_pip__installing:
+
 Installing ODL and its dependencies
 ===================================
 You may need to `install pip`_ to be able to install ODL and its dependencies from the `Python Package Index`_ (PyPI).
@@ -53,7 +62,8 @@ For basic installation without extra dependencies, run
 
    $ pip install --user odl
 
-.. _installing_odl_pip_extensions:
+
+.. _installing_odl_pip__extensions:
 
 Extra dependencies
 ------------------
@@ -72,13 +82,16 @@ Possible choices:
 - ``pywavelets`` : Install `PyWavelets`_ for wavelet transforms.
 - ``scikit`` : Install `scikit-image`_ as a simple backend for ray transforms.
 - ``proximal``: Install the `ProxImaL`_ convex optimization package.
-- ``testing``: Pull in the dependencies for unit tests (see :ref:`running_the_tests`)
+- ``testing``: Pull in the dependencies for unit tests (see :ref:`installing_odl_pip__running_the_tests`)
 
 These dependencies are optional and may not be easy to install on your system (especially on Windows).
 In general, a clean ODL installation is enough for most users' initial needs.
 
 More information can be found in :ref:`installing_odl_extensions`.
 
+
+.. _installing_odl_pip__running_the_tests:
+
 Running the tests
 =================
 Unit tests in ODL are based on `pytest`_.

doc/source/getting_started/installing_source.rst

@@ -24,7 +24,7 @@ Instructions for the impatient:
 
   Don't use the ``--user`` option together with ``conda``.
 
-- Install the :ref:`extensions you want<Extra dependencies>`.
+- Install the :ref:`extensions you want <installing_odl_extensions>`.
 
 
 Introduction
@@ -34,7 +34,7 @@ You also need `pip`_ to perform the installation.
 
 .. note::
     You should consider performing all described steps in a `conda environment <http://conda.pydata.org/docs/using/envs.html>`_ -- it gives you the same encapsulation benefits as developer that you would enjoy also as a user (no conflicting packages, free to choose Python version, ...).
-    See the :ref:`Installing Anaconda` section for setup instructions.
+    See the :ref:`installing_odl_conda__installing_anaconda` section for setup instructions.
 
 To get ODL, navigate to a folder where you want the ODL repository to be stored and clone the repository with the command
 
@@ -47,7 +47,7 @@ No GitHub account is required for this step.
 
 In a conda environment
 ======================
-This part assumes that you have activated a conda environment before (see :ref:`installing_odl_conda`).
+This part assumes that you have activated a conda environment before (see :ref:`installing_odl_conda__installing_anaconda`).
 
 You can choose to install dependencies first:
 
@@ -105,7 +105,7 @@ You may also want to install optional dependencies:
 Extra dependencies
 ------------------
 As a developer, you may want to install further optional dependencies.
-Consult the :ref:`pip<installing_odl_pip_extensions>` or :ref:`conda<installing_odl_conda_extensions>` guide for further instructions.
+Consult the :ref:`pip <installing_odl_pip__extensions>` or :ref:`conda <installing_odl_conda__extensions>` guide for further instructions.
 
 Running the tests
 =================