python: update docs with crosslinking and all the fancy stuff.

doc/python/conf.py

@@ -87,9 +87,13 @@ STYLESHEETS = [
 FAVICON = '../favicon.ico'
 
 M_DOX_TAGFILES = [
-    # TODO: the path should be relative to this file
+    ('../../../corrade/build/doc-mcss/corrade.tag', '../../../../corrade/build/doc-mcss/html/', ['Corrade::'],  ['m-doc-external']),
-    (os.path.join(os.path.dirname(__file__), '../../../corrade/build/doc-mcss/corrade.tag'), '../../../../corrade/build/doc-mcss/html/', ['Corrade::'],  ['m-doc-external']),
+    ('../../../magnum/build/doc-mcss/magnum.tag', '../../../../magnum/build/doc-mcss/html/', ['Magnum::'],  ['m-doc-external'])
-    (os.path.join(os.path.dirname(__file__), '../../../magnum/build/doc-mcss/magnum.tag'), '../../../../magnum/build/doc-mcss/html/', ['Magnum::'],  ['m-doc-external'])
+]
+M_SPHINX_INVENTORY_OUTPUT = 'objects.inv'
+M_SPHINX_INVENTORIES = [
+    ('python.inv', 'https://docs.python.org/3/', [], ['m-doc-external']),
+    ('numpy.inv', 'https://docs.scipy.org/doc/numpy/', [], ["m-doc-external"])
 ]
 M_HTMLSANITY_SMART_QUOTES = True
 

doc/python/magnum.math.rst

@@ -24,6 +24,16 @@
 ..
 
 .. py:module:: magnum.math
+    :data pi: :math:`\pi`
+    :data pi_half: Half of a :math:`\pi`
+    :data pi_quarter: Quarter of a :math:`\pi`
+    :data tau: :math:`\tau`, or :math:`2 \pi`
+    :data e: Euler's number
+    :data sqrt2: Square root of 2
+    :data sqrt3: Square root of 3
+    :data sqrt_half: Square root of :math:`\frac{1}{2}`
+    :data nan: Quiet NaN
+    :data inf: Positive :math:`\infty`
 
     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
@@ -83,12 +93,12 @@
 
         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 `math.sin()`
+        well-known Python APIs and constants. In particular, calling
-        expects an explicit `Deg` / `Rad` type, while Python's :py:`math.sin()`
+        `magnum.math.sin()` expects an explicit `Deg` / `Rad` type, while
-        doesn't. This will get resolved either by making all Python overloads
+        Python's `math.sin()` doesn't. This will get resolved either by making
-        present in the same module or giving the user an option whether to use
+        all Python overloads present in the same module or giving the user an
-        Magnum math or Python math. For now, to avoid confusion, do for example
+        option whether to use Magnum math or Python math. For now, to avoid
-        this:
+        confusion, do for example this:
 
         .. code:: pycon
 
@@ -104,9 +114,10 @@
 
     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` or `math.sin()`) use the :cpp:`double`
+    the `Deg` / `Rad` types, `math.pi <magnum.math.pi>` or
-    variant of the underlying C++ API --- the extra arithmetic cost is
+    `math.sin <magnum.math.sin()>`) use the :cpp:`double` variant of the
-    negligible to the Python-to-C++ function call overhead.
+    underlying C++ API --- the extra arithmetic cost is negligible to the
+    Python-to-C++ function call overhead.
 
     On the other hand, matrix and vector types are exposed in both the float
     and double variants.
@@ -117,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.array`, so the following
+    makes them fully compatible with `numpy.ndarray`, so the following
     expressions are completely valid:
 
     ..
@@ -210,33 +221,3 @@
         the corresponding :py:`mat.translation` property is temporarily
         available as an underscored `Matrix3._translation`. This will change
         later.
-
-.. py:data:: magnum.math.pi
-    :summary: :math:`\pi`
-
-.. py:data:: magnum.math.pi_half
-    :summary: Half of a :math:`\pi`
-
-.. py:data:: magnum.math.pi_quarter
-    :summary: Quarter of a :math:`\pi`
-
-.. py:data:: magnum.math.tau
-    :summary: :math:`\tau`
-
-.. py:data:: magnum.math.e
-    :summary: Euler's number
-
-.. py:data:: magnum.math.sqrt2
-    :summary: Square root of 2
-
-.. py:data:: magnum.math.sqrt3
-    :summary: Square root of 3
-
-.. py:data:: magnum.math.sqrt_half
-    :summary: Square root of :math:`\frac{1}{2}`
-
-.. py:data:: magnum.math.nan
-    :summary: Quiet NaN
-
-.. py:data:: magnum.math.inf
-    :summary: Positive :math:`\infty`

doc/python/magnum.platform.rst

@@ -28,9 +28,9 @@
     While concrete implementations of :py:`Application` and
     :py:`WindowlessApplication` classes are available in the submodules,
     there's a convenience logic importing the most fitting implementation
-    that's available directly into the :py:`platform` module, meaning you can
+    that's available directly into the `platform` module, meaning you can do
-    do just this without having to think about a particular implementation,
+    just this without having to think about a particular implementation, for
-    for example:
+    example:
 
     .. code:: py
 

doc/python/magnum.rst

@@ -29,11 +29,8 @@
     :language: c++
 .. role:: py(code)
     :language: py
-.. role:: link-ref(link)
-    :class: m-doc
 
 .. doctest setup
     >>> from magnum import *
 
-.. TODO: change this to py:ref or something when we are able to reference names
+.. default-role:: ref
-.. default-role:: py

doc/python/pages/api-conventions.rst

@@ -26,8 +26,11 @@
 Python API conventions
 ######################
 
-:summary: Basic rules and good practices for both Python binding develpoers and
+:summary: Basic rules and good practices for both Python binding developers and
     users.
+:ref-prefix:
+    corrade
+    magnum
 
 `API naming`_
 =============
@@ -70,14 +73,14 @@ C++                                 Python
 
 .. class:: m-table
 
-================================================ ==========================
+=============================================================== ===========
-C++                                              Python
+C++                                                             Python
-================================================ ==========================
+=============================================================== ===========
-:dox:`Math::angle()`                             `math.angle()`
+:dox:`Math::angle()`                                            `math.angle()`
-:dox:`Vector2::xAxis() <Math::Vector2::xAxis()>` `Vector2.x_axis()`
+:dox:`Vector2::xAxis() <Math::Vector2::xAxis()>`                `Vector2.x_axis()`
-:cpp:`v.isZero()`                                :py:`v.is_zero()`
+:dox:`v.isZero() <Math::Vector::isZero()>`                      `v.is_zero() <Vector3.is_zero()>`
-:cpp:`m.transformVector(a)`                      :py:`m.transform_vector(a)`
+:dox:`m.transformVector(a) <Math::Matrix4::transformVector()>`  `m.transform_vector(a) <Matrix4.transform_vector()>`
-================================================ ==========================
+=============================================================== ===========
 
 `Enums`_
 --------
@@ -88,14 +91,14 @@ C++                                              Python
 C++                                            Python
 ============================================== ============================
 :dox:`PixelFormat::RGB8Unorm`                  `PixelFormat.RGB8UNORM`
-:dox:`MeshPrimitive::TriangleStrip`            :py:`MeshPrimitive.TRIANGLE_STRIP`
+:dox:`MeshPrimitive::TriangleStrip`            `MeshPrimitive.TRIANGLE_STRIP`
 ============================================== ============================
 
 `Constants`_
 ------------
 
 Apart from :dox:`Math::Constants`, which are exposed directly as members of the
-`math` submodule to mimic Python's :py:`math`, most of the constants used
+`magnum.math` submodule to mimic Python's `math`, most of the constants used
 throughout the C++ API are related to templates. Those are, where applicable,
 converted to Python builtins such as :py:`len()`.
 
@@ -104,7 +107,7 @@ converted to Python builtins such as :py:`len()`.
 ============================================== ============================
 C++                                            Python
 ============================================== ============================
-:dox:`Constants::pi() <Math::Constants::pi()>` `math.pi`
+:dox:`Constants::pi() <Math::Constants::pi()>` `math.pi <magnum.math.pi>`
 :dox:`Math::Vector::Size`                      :py:`len(vec)`
 ============================================== ============================
 

doc/python/pages/building.rst

@@ -30,6 +30,9 @@ Downloading and building
     :language: sh
 
 :summary: Installation guide for the Python bindings.
+:ref-prefix:
+    corrade
+    magnum
 
 Building of Python bindings is a similar process to
 :dox:`building Magnum itself <building>` with an additional step involving
@@ -73,10 +76,10 @@ Once built, install the package using ``pacman``:
 ------------------------------
 
 macOS `Homebrew <https://brew.sh>`_ formulas building the latest Git revision
-are in the `package/homebrew` directory. Either use the `*.rb` files directly
+are in the ``package/homebrew`` directory. Either use the ``*.rb`` files
-or use the tap at https://github.com/mosra/homebrew-magnum. Right now, there's
+directly or use the tap at https://github.com/mosra/homebrew-magnum. Right now,
-no stable release of Python bindings yet, so you need to install the latest Git
+there's no stable release of Python bindings yet, so you need to install the
-revision of all Magnum projects instead:
+latest Git revision of all Magnum projects instead:
 
 .. code:: sh
 
@@ -84,14 +87,14 @@ revision of all Magnum projects instead:
     brew install --HEAD mosra/magnum/magnum
     brew install --HEAD mosra/magnum/magnum-bindings
 
-When installing from the `*.rb` files you need to install the
+When installing from the ``*.rb`` files you need to install the
 :dox:`Corrade <building-corrade-packages-brew>` and
 :dox:`Magnum <building-packages-brew>` Homebrew packages first. If you want to
 pass additional flags to CMake or ``setup.py`` or enable / disable additional
 features, edit the ``*.rb`` file.
 
 There are also Homebrew packages for
-:dox:`Magnum Plugins <building-plugins-packages-brew>`
+:dox:`Magnum Plugins <building-plugins-packages-brew>`,
 :dox:`Magnum Integration <building-integration-packages-brew>`,
 :dox:`Magnum Extras <building-extras-packages-brew>` and
 :dox:`Magnum Examples <building-examples-packages-brew>`.

doc/python/pages/index.rst

@@ -42,11 +42,11 @@ the C++ docs --- highlighting important differences and describing general
 conventions, but referring to documentation of underlying C++ APIs for all
 details.
 
-See the :link-ref:`building docs <building.html>` for an installation guide,
+See the `building docs <std:doc:building>` for an installation guide,
-:link-ref:`API convention documentation <api-conventions.html>` and
+`API convention documentation <std:doc:api-conventions>` and
-:link-ref:`documentation of each module <modules.html>` for more information
+`documentation of each module <std:special:modules>` for more information about
-about the actual usage. There are also :link-ref:`examples <examples.html>` to
+the actual usage. There are also `examples <std:doc:examples>` to give you an
-give you an idea about how the API feels.
+idea about how the API feels.
 
 `Contact & support`_
 ====================