diff --git a/doc/python/conf.py b/doc/python/conf.py index 35429d8..6307384 100644 --- a/doc/python/conf.py +++ b/doc/python/conf.py @@ -87,9 +87,13 @@ STYLESHEETS = [ FAVICON = '../favicon.ico' M_DOX_TAGFILES = [ - # TODO: the path should be relative to this file - (os.path.join(os.path.dirname(__file__), '../../../corrade/build/doc-mcss/corrade.tag'), '../../../../corrade/build/doc-mcss/html/', ['Corrade::'], ['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']) + ('../../../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']) +] +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 diff --git a/doc/python/magnum.math.rst b/doc/python/magnum.math.rst index 1388c94..4213d38 100644 --- a/doc/python/magnum.math.rst +++ b/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()` - expects an explicit `Deg` / `Rad` type, while Python's :py:`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: + 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: .. 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` - variant of the underlying C++ API --- the extra arithmetic cost is - negligible to the Python-to-C++ function call overhead. + the `Deg` / `Rad` types, `math.pi ` or + `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. 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` diff --git a/doc/python/magnum.platform.rst b/doc/python/magnum.platform.rst index 4c5abc2..5c7e09f 100644 --- a/doc/python/magnum.platform.rst +++ b/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 - do just this without having to think about a particular implementation, - for example: + that's available directly into the `platform` module, meaning you can do + just this without having to think about a particular implementation, for + example: .. code:: py diff --git a/doc/python/magnum.rst b/doc/python/magnum.rst index 6118a10..c79c54d 100644 --- a/doc/python/magnum.rst +++ b/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:: py +.. default-role:: ref diff --git a/doc/python/numpy.inv b/doc/python/numpy.inv new file mode 100644 index 0000000..e8aa0b2 Binary files /dev/null and b/doc/python/numpy.inv differ diff --git a/doc/python/pages/api-conventions.rst b/doc/python/pages/api-conventions.rst index 01396a9..024f70c 100644 --- a/doc/python/pages/api-conventions.rst +++ b/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 -================================================ ========================== -:dox:`Math::angle()` `math.angle()` -:dox:`Vector2::xAxis() ` `Vector2.x_axis()` -:cpp:`v.isZero()` :py:`v.is_zero()` -:cpp:`m.transformVector(a)` :py:`m.transform_vector(a)` -================================================ ========================== +=============================================================== =========== +C++ Python +=============================================================== =========== +:dox:`Math::angle()` `math.angle()` +:dox:`Vector2::xAxis() ` `Vector2.x_axis()` +:dox:`v.isZero() ` `v.is_zero() ` +:dox:`m.transformVector(a) ` `m.transform_vector(a) ` +=============================================================== =========== `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.pi` +:dox:`Constants::pi() ` `math.pi ` :dox:`Math::Vector::Size` :py:`len(vec)` ============================================== ============================ diff --git a/doc/python/pages/building.rst b/doc/python/pages/building.rst index e5cf629..275d9bf 100644 --- a/doc/python/pages/building.rst +++ b/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 ` with an additional step involving @@ -73,10 +76,10 @@ Once built, install the package using ``pacman``: ------------------------------ macOS `Homebrew `_ formulas building the latest Git revision -are in the `package/homebrew` directory. Either use the `*.rb` files directly -or use the tap at https://github.com/mosra/homebrew-magnum. Right now, there's -no stable release of Python bindings yet, so you need to install the latest Git -revision of all Magnum projects instead: +are in the ``package/homebrew`` directory. Either use the ``*.rb`` files +directly or use the tap at https://github.com/mosra/homebrew-magnum. Right now, +there's no stable release of Python bindings yet, so you need to install the +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 ` and :dox:`Magnum ` 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 ` +:dox:`Magnum Plugins `, :dox:`Magnum Integration `, :dox:`Magnum Extras ` and :dox:`Magnum Examples `. diff --git a/doc/python/pages/index.rst b/doc/python/pages/index.rst index 07d3a0a..7b527c0 100644 --- a/doc/python/pages/index.rst +++ b/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 ` for an installation guide, -:link-ref:`API convention documentation ` and -:link-ref:`documentation of each module ` for more information -about the actual usage. There are also :link-ref:`examples ` to -give you an idea about how the API feels. +See the `building docs ` for an installation guide, +`API convention documentation ` and +`documentation of each module ` for more information about +the actual usage. There are also `examples ` to give you an +idea about how the API feels. `Contact & support`_ ==================== diff --git a/doc/python/python.inv b/doc/python/python.inv new file mode 100644 index 0000000..a08de13 Binary files /dev/null and b/doc/python/python.inv differ