doc: switch to explicit :ref: as default roles don't work well.

doc/python/corrade.containers.rst

@@ -30,11 +30,11 @@
 
     Provides one-dimensional tightly packed view on a memory range. Convertible
     both from and to Python objects supporting the Buffer Protocol, with one
-    dimension and stride of :py:`1`. See `StridedArrayView1D` and others for
-    more generic views. `ArrayView` is immutable, see `MutableArrayView` for
-    the mutable alterantive. All slicing operations are supported, specifying a
-    non-trivial stride will return `StridedArrayView1D` instead of `ArrayView`.
-    Example usage:
+    dimension and stride of :py:`1`. See :ref:`StridedArrayView1D` and others
+    for more generic views. :ref:`ArrayView` is immutable, see
+    :ref:`MutableArrayView` for the mutable alterantive. All slicing operations
+    are supported, specifying a non-trivial stride will return
+    :ref:`StridedArrayView1D` instead of :ref:`ArrayView`. Example usage:
 
     .. code:: pycon
 
@@ -49,10 +49,10 @@
     ==========================================
 
     Unlike in C++, the view keeps a reference to the original memory owner
-    object in the `owner` field, meaning that calling :py:`del` on the original
-    object will *not* invalidate the view. Slicing a view creates a new view
-    referencing the same original object, without any dependency on the
-    previous view. That means a long chained slicing operation will not cause
+    object in the :ref:`owner` field, meaning that calling :py:`del` on the
+    original object will *not* invalidate the view. Slicing a view creates a
+    new view referencing the same original object, without any dependency on
+    the previous view. That means a long chained slicing operation will not cause
     increased memory usage.
 
     .. code:: pycon
@@ -62,53 +62,55 @@
         >>> b[1:4][:-1].owner is a
         True
 
-    The `owner` is :py:`None` if the view is empty.
+    The :py:`owner` is :py:`None` if the view is empty.
 
     `Comparison to Python's memoryview`_
     ====================================
 
-    The `ArrayView` class is equivalent to one-dimensional `memoryview` with a
-    stride of :py:`1`. For multiple dimensions and non-trivial strides,
-    `StridedArrayView1D` and friends provide a superset of `memoryview`
-    features.
+    The :ref:`ArrayView` class is equivalent to one-dimensional
+    :ref:`memoryview` with a stride of :py:`1`. For multiple dimensions and
+    non-trivial strides, :ref:`StridedArrayView1D` and friends provide a
+    superset of :ref:`memoryview` features.
 
 .. py:class:: corrade.containers.MutableArrayView
 
-    Equivalent to `ArrayView`, but implementing `__setitem__()` as well.
+    Equivalent to :ref:`ArrayView`, but implementing :ref:`__setitem__()` as
+    well.
 
 .. py:class:: corrade.containers.StridedArrayView1D
 
     Provides one-dimensional read-only view on a memory range with custom
-    stride values. See `StridedArrayView2D`, `StridedArrayView3D`,
-    `MutableStridedArrayView1D` and others for multi-dimensional and mutable
-    equivalents.
+    stride values. See :ref:`StridedArrayView2D`, :ref:`StridedArrayView3D`,
+    :ref:`MutableStridedArrayView1D` and others for multi-dimensional and
+    mutable equivalents.
 
     `Comparison to Python's memoryview`_
     ====================================
 
-    The `StridedArrayView1D` and its multi-dimensional variants are equivalent
-    to any `memoryview`, but additionally supporting multi-dimensional slicing
-    as well (which raises `NotImplementedError` in Py3.7 `memoryview`).
+    The :ref:`StridedArrayView1D` and its multi-dimensional variants are
+    equivalent to any :ref:`memoryview`, but additionally supporting
+    multi-dimensional slicing as well (which raises :ref:`NotImplementedError`
+    in Py3.7 :ref:`memoryview`).
 
 .. py:class:: corrade.containers.MutableStridedArrayView1D
 
-    Equivalent to `StridedArrayView1D`, but implementing `__setitem__()` as
-    well.
+    Equivalent to :ref:`StridedArrayView1D`, but implementing
+    :ref:`__setitem__()` as well.
 
 .. py:class:: corrade.containers.StridedArrayView2D
 
-    See `StridedArrayView1D` for more information.
+    See :ref:`StridedArrayView1D` for more information.
 
 .. py:class:: corrade.containers.MutableStridedArrayView2D
 
-    See `StridedArrayView1D` and `MutableStridedArrayView1D` for more
+    See :ref:`StridedArrayView1D` and :ref:`MutableStridedArrayView1D` for more
     information.
 
 .. py:class:: corrade.containers.StridedArrayView3D
 
-    See `StridedArrayView1D` for more information.
+    See :ref:`StridedArrayView1D` for more information.
 
 .. py:class:: corrade.containers.MutableStridedArrayView3D
 
-    See `StridedArrayView1D` and `MutableStridedArrayView1D` for more
+    See :ref:`StridedArrayView1D` and :ref:`MutableStridedArrayView1D` for more
     information.

doc/python/corrade.pluginmanager.rst

@@ -28,9 +28,9 @@
 
 .. py:function:: corrade.pluginmanager.AbstractManager.load
     :raise RuntimeError: When loading fails
-    :return: `LoadState.LOADED`, possibly combined with other flags such as
-        `LoadState.STATIC`
+    :return: :ref:`LoadState.LOADED`, possibly combined with other flags such
+        as :ref:`LoadState.STATIC`
 
 .. py:function:: corrade.pluginmanager.AbstractManager.unload
     :raise RuntimeError: When unloading fails
-    :return: Either `LoadState.NOT_LOADED` or `LoadState.STATIC`
+    :return: Either :ref:`LoadState.NOT_LOADED` or :ref:`LoadState.STATIC`

doc/python/corrade.rst

@@ -35,8 +35,6 @@
 .. doctest setup
     >>> from corrade import *
 
-.. default-role:: ref
-
 .. py:module:: corrade
     :data BUILD_STATIC: Static library build
     :data BUILD_MULTITHREADED: Multi-threaded build

doc/python/magnum.gl.rst

@@ -26,8 +26,7 @@
 .. py:module:: magnum.gl
     :data default_framebuffer: Default framebuffer instance
 
-    TODO: remove this once m.css stops ignoring the first caption on a page
-    #######################################################################
+    :TODO: remove this line once m.css stops ignoring first caption on a page
 
     `NoCreate constructors`_
     ========================
@@ -50,50 +49,50 @@
 
 .. py:class:: magnum.gl.Mesh
 
-    TODO: remove this once m.css stops ignoring the first caption on a page
-    #######################################################################
+    :TODO: remove this line once m.css stops ignoring first caption on a page
 
     `Buffer ownership and reference counting`_
     ==========================================
 
     Unlike in C++, where a :dox:`GL::Buffer` is either :dox:`std::move()`\ d
     into the mesh or referenced externally (with the user being responsible for
-    its lifetime), the `gl.Mesh` object keeps references to all buffers added
-    to it.
+    its lifetime), the :ref:`gl.Mesh` object keeps references to all buffers
+    added to it.
 
 .. py:property:: magnum.gl.Mesh.primitive
 
-    While querying this property will always give back a `gl.MeshPrimitive`,
-    this property can be set using either `magnum.MeshPrimitive` or
-    `gl.MeshPrimitive`, similarly to how the overloaded
+    While querying this property will always give back a :ref:`gl.MeshPrimitive`,
+    this property can be set using either :ref:`magnum.MeshPrimitive` or
+    :ref:`gl.MeshPrimitive`, similarly to how the overloaded
     :dox:`GL::Mesh::setPrimitive()` works.
 
 .. py:property:: magnum.gl.Texture1D.minification_filter
 
-    See `Texture2D.minification_filter` for more information.
+    See :ref:`Texture2D.minification_filter` for more information.
 
 .. py:property:: magnum.gl.Texture2D.minification_filter
 
-    This property accepts either a tuple of `magnum.SamplerFilter` /
-    `gl.SamplerFilter` and `magnum.SamplerMipmap` / `gl.SamplerMipmap` values
-    or just `magnum.SamplerFilter` / `gl.SamplerFilter` alone in which case
-    `gl.SamplerMipmap.BASE` will be used implicitly; similarly to how the
-    overloaded :dox:`GL::Texture::setMinificationFilter()` works.
+    This property accepts either a tuple of :ref:`magnum.SamplerFilter` /
+    :ref:`gl.SamplerFilter` and :ref:`magnum.SamplerMipmap` /
+    :ref:`gl.SamplerMipmap` values or just :ref:`magnum.SamplerFilter` / :ref:`gl.SamplerFilter` alone in which case :ref:`gl.SamplerMipmap.BASE`
+    will be used implicitly; similarly to how the overloaded
+    :dox:`GL::Texture::setMinificationFilter()` works.
 
 .. py:property:: magnum.gl.Texture3D.minification_filter
 
-    See `Texture2D.minification_filter` for more information.
+    See :ref:`Texture2D.minification_filter` for more information.
 
 .. py:property:: magnum.gl.Texture1D.magnification_filter
 
-    See `Texture2D.magnification_filter` for more information.
+    See :ref:`Texture2D.magnification_filter` for more information.
 
 .. py:property:: magnum.gl.Texture2D.magnification_filter
 
-    This property accepts either `magnum.SamplerFilter` or `gl.SamplerFilter`,
-    similarly to how the overloaded :dox:`GL::Texture::setMagnificationFilter()`
+    This property accepts either :ref:`magnum.SamplerFilter` or
+    :ref:`gl.SamplerFilter`, similarly to how the overloaded
+    :dox:`GL::Texture::setMagnificationFilter()`
     works.
 
 .. py:property:: magnum.gl.Texture3D.magnification_filter
 
-    See `Texture2D.magnification_filter` for more information.
+    See :ref:`Texture2D.magnification_filter` for more information.

doc/python/magnum.math.rst

@@ -38,7 +38,7 @@
     In the C++ API, math types are commonly used via :cpp:`typedef`\ s in the
     root namespace, only library-level generic code uses things like
     :dox:`Math::Vector<size, T> <Math::Vector>`. Since Python doesn't have
-    templates or generics, there are no generic variants in the `magnum.math`
+    templates or generics, there are no generic variants in the :ref:`magnum.math`
     module, all the concrete types are in the root module with the same names
     as in the C++ variant.
 
@@ -82,7 +82,7 @@
 
     As shown above, all math types are constructible from a (nested) tuple of
     matching type, matching the convenience of C++11 uniform initializers. As
-    another example, a function accepting a `Quaternion` will accept a
+    another example, a function accepting a :ref:`Quaternion` will accept a
     :py:`((x, y, z), w)` tuple as well, but not :py:`(x, y, z, w)`, as that is
     not convertible to a pair of a three-component vector and a scalar.
 
@@ -94,11 +94,11 @@
         Currently, doing :py:`from magnum import math` will bring in the
         Magnum's math module which at the moment *does not* contain the
         well-known Python APIs and constants. In particular, calling
-        `magnum.math.sin()` expects an explicit `Deg` / `Rad` type, while
-        Python's `math.sin()` doesn't. This will get resolved either by making
-        all Python overloads present in the same module or giving the user an
-        option whether to use Magnum math or Python math. For now, to avoid
-        confusion, do for example this:
+        :ref:`magnum.math.sin()` expects an explicit :ref:`Deg` / :ref:`Rad`
+        type, while Python's :ref:`math.sin()` doesn't. This will get resolved
+        either by making all Python overloads present in the same module or
+        giving the user an option whether to use Magnum math or Python math.
+        For now, to avoid confusion, do for example this:
 
         .. code:: pycon
 
@@ -114,8 +114,8 @@
 
     Since Python doesn't really differentiate between 32bit and 64bit doubles,
     all *scalar* functions taking or returning a floating-point type (such as
-    the `Deg` / `Rad` types, `math.pi <magnum.math.pi>` or
-    `math.sin <magnum.math.sin()>`) use the :cpp:`double` variant of the
+    the :ref:`Deg` / :ref:`Rad` types, :ref:`math.pi <magnum.math.pi>` or
+    :ref:`math.sin <magnum.math.sin()>`) use the :cpp:`double` variant of the
     underlying C++ API --- the extra arithmetic cost is negligible to the
     Python-to-C++ function call overhead.
 
@@ -128,7 +128,7 @@
     All vector classes are implicitly convertible from a tuple of correct size
     and type as well as from/to type implementing the buffer protocol, and
     these can be also converted back to lists using list comprehensions. This
-    makes them fully compatible with `numpy.ndarray`, so the following
+    makes them fully compatible with :ref:`numpy.ndarray`, so the following
     expressions are completely valid:
 
     ..
@@ -214,11 +214,11 @@
     `Static constructors and instance method / property overloads`_
     ---------------------------------------------------------------
 
-    While not common in Python, the `Matrix4.scaling()` / `Matrix4.rotation()`
-    methods mimic the C++ equivalent --- calling :py:`Matrix4.scaling(vec)`
-    will return a scaling matrix, while :py:`mat.scaling()` returns the 3x3
-    scaling part of the matrix. With `Matrix4.translation`, it's a bit more
-    involved --- calling :py:`Matrix4.translation(vec)` will return a
-    translation matrix, while :py:`mat.translation` is a read-write property
-    accessing the fourth column of the matrix. Similarly for the `Matrix3`
-    class.
+    While not common in Python, the :ref:`Matrix4.scaling()` /
+    :ref:`Matrix4.rotation()` methods mimic the C++ equivalent --- calling
+    :py:`Matrix4.scaling(vec)` will return a scaling matrix, while
+    :py:`mat.scaling()` returns the 3x3 scaling part of the matrix. With
+    :ref:`Matrix4.translation`, it's a bit more involved --- calling
+    :py:`Matrix4.translation(vec)` will return a translation matrix, while
+    :py:`mat.translation` is a read-write property accessing the fourth column
+    of the matrix. Similarly for the :ref:`Matrix3` class.