From be5ffdd9168e968e50486b3023e65408000d7493 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 6 Oct 2020 12:49:52 +0200 Subject: [PATCH] doc: switch to explicit :ref: as default roles don't work well. --- doc/python/corrade.containers.rst | 56 +++++++++---------- doc/python/corrade.pluginmanager.rst | 6 +-- doc/python/corrade.rst | 2 - doc/python/magnum.gl.rst | 39 +++++++------- doc/python/magnum.math.rst | 36 ++++++------- doc/python/magnum.rst | 65 +++++++++++----------- doc/python/magnum.shaders.rst | 32 ++++++----- doc/python/magnum.trade.rst | 80 ++++++++++++++++------------ doc/python/pages/api-conventions.rst | 51 +++++++++--------- doc/python/pages/building.rst | 6 +-- doc/python/pages/changelog.rst | 27 +++++----- doc/python/pages/index.rst | 10 ++-- 12 files changed, 214 insertions(+), 196 deletions(-) diff --git a/doc/python/corrade.containers.rst b/doc/python/corrade.containers.rst index dbc903ea..e3497ffc 100644 --- a/doc/python/corrade.containers.rst +++ b/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. diff --git a/doc/python/corrade.pluginmanager.rst b/doc/python/corrade.pluginmanager.rst index c64672b6..f3aa9d54 100644 --- a/doc/python/corrade.pluginmanager.rst +++ b/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` diff --git a/doc/python/corrade.rst b/doc/python/corrade.rst index 3553af88..97eaf067 100644 --- a/doc/python/corrade.rst +++ b/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 diff --git a/doc/python/magnum.gl.rst b/doc/python/magnum.gl.rst index 147306b5..527f779f 100644 --- a/doc/python/magnum.gl.rst +++ b/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. diff --git a/doc/python/magnum.math.rst b/doc/python/magnum.math.rst index f424527e..5e44b4b1 100644 --- a/doc/python/magnum.math.rst +++ b/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 `. 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 ` or - `math.sin `) use the :cpp:`double` variant of the + the :ref:`Deg` / :ref:`Rad` types, :ref:`math.pi ` or + :ref:`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. diff --git a/doc/python/magnum.rst b/doc/python/magnum.rst index 4398f77a..503725a8 100644 --- a/doc/python/magnum.rst +++ b/doc/python/magnum.rst @@ -38,88 +38,89 @@ .. py:class:: magnum.Image1D - See `Image2D` for more information. + See :ref:`Image2D` for more information. .. py:class:: magnum.Image2D - An owning counterpart to `ImageView2D` / `MutableImageView2D`. Holds its - own data buffer, thus doesn't have an equivalent to `ImageView2D.owner`. - Implicitly convertible to `ImageView2D` / `MutableImageView2D`, so all APIs - consuming image views work with this type as well. + An owning counterpart to :ref:`ImageView2D` / :ref:`MutableImageView2D`. + Holds its own data buffer, thus doesn't have an equivalent to + :ref:`ImageView2D.owner`. Implicitly convertible to :ref:`ImageView2D` / + :ref:`MutableImageView2D`, so all APIs consuming image views work with this + type as well. .. py:class:: magnum.Image3D - See `Image2D` for more information. + See :ref:`Image2D` for more information. .. py:class:: magnum.ImageView1D - See `ImageView2D` for more information. + See :ref:`ImageView2D` for more information. .. py:class:: magnum.ImageView2D - 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 `Memory ownership and reference counting`_ ========================================== - Similarly to `corrade.containers.ArrayView` (and 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 increased memory usage. + Similarly to :ref:`corrade.containers.ArrayView` (and unlike in C++), the + view keeps a reference to the original memory owner 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. - The `owner` is :py:`None` if the view is empty. + The :ref:`owner` is :py:`None` if the view is empty. .. py:class:: magnum.ImageView3D - See `ImageView2D` for more information. + See :ref:`ImageView2D` for more information. .. py:class:: magnum.MutableImageView1D - See `ImageView2D` for more information. + See :ref:`ImageView2D` for more information. .. py:class:: magnum.MutableImageView2D - See `ImageView2D` for more information. + See :ref:`ImageView2D` for more information. .. py:class:: magnum.MutableImageView3D - See `ImageView2D` for more information. + See :ref:`ImageView2D` for more information. .. py:function:: magnum.ImageView1D.__init__(self, arg0: magnum.ImageView1D) - :raise RuntimeError: If `trade.ImageData1D.is_compressed` is :py:`True` + :raise RuntimeError: If :ref:`trade.ImageData1D.is_compressed` is :py:`True` This function is used to implement implicit conversion from - `trade.ImageData1D` in the `trade` module. + :ref:`trade.ImageData1D` in the :ref:`trade` module. .. py:function:: magnum.ImageView2D.__init__(self, arg0: magnum.ImageView2D) - :raise RuntimeError: If `trade.ImageData2D.is_compressed` is :py:`True` + :raise RuntimeError: If :ref:`trade.ImageData2D.is_compressed` is :py:`True` This function is used to implement implicit conversion from - `trade.ImageData2D` in the `trade` module. + :ref:`trade.ImageData2D` in the :ref:`trade` module. .. py:function:: magnum.ImageView3D.__init__(self, arg0: magnum.ImageView3D) - :raise RuntimeError: If `trade.ImageData3D.is_compressed` is :py:`True` + :raise RuntimeError: If :ref:`trade.ImageData3D.is_compressed` is :py:`True` This function is used to implement implicit conversion from - `trade.ImageData3D` in the `trade` module. + :ref:`trade.ImageData3D` in the :ref:`trade` module. .. py:function:: magnum.MutableImageView1D.__init__(self, arg0: magnum.MutableImageView1D) - :raise RuntimeError: If `trade.ImageData1D.is_compressed` is :py:`True` + :raise RuntimeError: If :ref:`trade.ImageData1D.is_compressed` is :py:`True` This function is used to implement implicit conversion from - `trade.ImageData1D` in the `trade` module. + :ref:`trade.ImageData1D` in the :ref:`trade` module. .. py:function:: magnum.MutableImageView2D.__init__(self, arg0: magnum.MutableImageView2D) - :raise RuntimeError: If `trade.ImageData2D.is_compressed` is :py:`True` + :raise RuntimeError: If :ref:`trade.ImageData2D.is_compressed` is :py:`True` This function is used to implement implicit conversion from - `trade.ImageData2D` in the `trade` module. + :ref:`trade.ImageData2D` in the :ref:`trade` module. .. py:function:: magnum.MutableImageView3D.__init__(self, arg0: magnum.MutableImageView3D) - :raise RuntimeError: If `trade.ImageData3D.is_compressed` is :py:`True` + :raise RuntimeError: If :ref:`trade.ImageData3D.is_compressed` is :py:`True` This function is used to implement implicit conversion from - `trade.ImageData3D` in the `trade` module. + :ref:`trade.ImageData3D` in the :ref:`trade` module. diff --git a/doc/python/magnum.shaders.rst b/doc/python/magnum.shaders.rst index 31832487..f81dcaf4 100644 --- a/doc/python/magnum.shaders.rst +++ b/doc/python/magnum.shaders.rst @@ -36,14 +36,18 @@ :data COLOR4: Four-component vertex color .. py:property:: magnum.shaders.Flat2D.alpha_mask - :raise AttributeError: If the shader was not created with `Flags.ALPHA_MASK` + :raise AttributeError: If the shader was not created with + :ref:`Flags.ALPHA_MASK` .. py:property:: magnum.shaders.Flat3D.alpha_mask - :raise AttributeError: If the shader was not created with `Flags.ALPHA_MASK` + :raise AttributeError: If the shader was not created with + :ref:`Flags.ALPHA_MASK` .. py:function:: magnum.shaders.Flat2D.bind_texture - :raise AttributeError: If the shader was not created with `Flags.TEXTURED` + :raise AttributeError: If the shader was not created with + :ref:`Flags.TEXTURED` .. py:function:: magnum.shaders.Flat3D.bind_texture - :raise AttributeError: If the shader was not created with `Flags.TEXTURED` + :raise AttributeError: If the shader was not created with + :ref:`Flags.TEXTURED` .. py:class:: magnum.shaders.VertexColor2D :data POSITION: Vertex position @@ -64,25 +68,27 @@ :data COLOR4: Four-component vertex color .. py:property:: magnum.shaders.Phong.alpha_mask - :raise AttributeError: If the shader was not created with `Flags.ALPHA_MASK` + :raise AttributeError: If the shader was not created with + :ref:`Flags.ALPHA_MASK` .. py:property:: magnum.shaders.Phong.light_positions - :raise ValueError: If list length is different from `light_count` + :raise ValueError: If list length is different from :ref:`light_count` .. py:property:: magnum.shaders.Phong.light_colors - :raise ValueError: If list length is different from `light_count` + :raise ValueError: If list length is different from :ref:`light_count` .. py:function:: magnum.shaders.Phong.bind_ambient_texture :raise AttributeError: If the shader was not created with - `Flags.AMBIENT_TEXTURE` + :ref:`Flags.AMBIENT_TEXTURE` .. py:function:: magnum.shaders.Phong.bind_diffuse_texture :raise AttributeError: If the shader was not created with - `Flags.DIFFUSE_TEXTURE` + :ref:`Flags.DIFFUSE_TEXTURE` .. py:function:: magnum.shaders.Phong.bind_specular_texture :raise AttributeError: If the shader was not created with - `Flags.SPECULAR_TEXTURE` + :ref:`Flags.SPECULAR_TEXTURE` .. py:function:: magnum.shaders.Phong.bind_normal_texture :raise AttributeError: If the shader was not created with - `Flags.NORMAL_TEXTURE` + :ref:`Flags.NORMAL_TEXTURE` .. py:function:: magnum.shaders.Phong.bind_textures :raise AttributeError: If the shader was not created with any of - `Flags.AMBIENT_TEXTURE`, `Flags.DIFFUSE_TEXTURE`, - `Flags.SPECULAR_TEXTURE` or `Flags.NORMAL_TEXTURE` + :ref:`Flags.AMBIENT_TEXTURE`, :ref:`Flags.DIFFUSE_TEXTURE`, + :ref:`Flags.SPECULAR_TEXTURE` or :ref:`Flags.NORMAL_TEXTURE` + diff --git a/doc/python/magnum.trade.rst b/doc/python/magnum.trade.rst index b8718e53..7f3c0bd7 100644 --- a/doc/python/magnum.trade.rst +++ b/doc/python/magnum.trade.rst @@ -25,57 +25,58 @@ .. py:class:: magnum.trade.ImageData1D - See `ImageData2D` for more information. + See :ref:`ImageData2D` for more information. .. py:class:: magnum.trade.ImageData2D - Similarly to `Image2D`, holds its own data buffer, thus doesn't have an - equivalent to `ImageView2D.owner`. Implicitly convertible to `ImageView2D` - / `MutableImageView2D`, so all APIs consuming image views work with this - type as well. + Similarly to :ref:`Image2D`, holds its own data buffer, thus doesn't have + an equivalent to :ref:`ImageView2D.owner`. Implicitly convertible to + :ref:`ImageView2D` / :ref:`MutableImageView2D`, so all APIs consuming image + views work with this type as well. .. py:class:: magnum.trade.ImageData3D - See `ImageData2D` for more information. + See :ref:`ImageData2D` for more information. .. py:property:: magnum.trade.ImageData1D.storage - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData2D.storage - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData3D.storage - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData1D.format - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData2D.format - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData3D.format - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData1D.pixel_size - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData2D.pixel_size - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData3D.pixel_size - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData1D.pixels - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData2D.pixels - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:property:: magnum.trade.ImageData3D.pixels - :raise AttributeError: If `is_compressed` is :py:`True` + :raise AttributeError: If :ref:`is_compressed` is :py:`True` .. py:class:: magnum.trade.ImporterManager - :summary: Manager for `AbstractImporter` plugin instances + :summary: Manager for :ref:`AbstractImporter` plugin instances - Each plugin returned by `instantiate()` or `load_and_instantiate()` - references its owning `ImporterManager` through `AbstractImporter.manager`, - ensuring the manager is not deleted before the plugin instances are. + Each plugin returned by :ref:`instantiate()` or :ref:`load_and_instantiate()` + references its owning :ref:`ImporterManager` through + :ref:`AbstractImporter.manager`, ensuring the manager is not deleted before + the plugin instances are. .. py:class:: magnum.trade.AbstractImporter - Similarly to C++, importer plugins are loaded through `ImporterManager`: + Similarly to C++, importer plugins are loaded through :ref:`ImporterManager`: .. >>> from magnum import trade @@ -99,15 +100,15 @@ :raise RuntimeError: If no file is opened .. py:function:: magnum.trade.AbstractImporter.mesh_level_count :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `mesh_count` + :raise ValueError: If :p:`id` is negative or not less than :ref:`mesh_count` .. py:function:: magnum.trade.AbstractImporter.mesh_for_name :raise RuntimeError: If no file is opened .. py:function:: magnum.trade.AbstractImporter.mesh_name :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `mesh_count` + :raise ValueError: If :p:`id` is negative or not less than :ref:`mesh_count` .. py:function:: magnum.trade.AbstractImporter.mesh :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `mesh_count` + :raise ValueError: If :p:`id` is negative or not less than :ref:`mesh_count` .. py:property:: magnum.trade.AbstractImporter.image1d_count :raise RuntimeError: If no file is opened @@ -118,13 +119,16 @@ .. py:function:: magnum.trade.AbstractImporter.image1d_level_count :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `image1d_count` + :raise ValueError: If :p:`id` is negative or not less than + :ref:`image1d_count` .. py:function:: magnum.trade.AbstractImporter.image2d_level_count :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `image2d_count` + :raise ValueError: If :p:`id` is negative or not less than + :ref:`image2d_count` .. py:function:: magnum.trade.AbstractImporter.image3d_level_count :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `image3d_count` + :raise ValueError: If :p:`id` is negative or not less than + :ref:`image3d_count` .. py:function:: magnum.trade.AbstractImporter.image1d_for_name :raise RuntimeError: If no file is opened @@ -135,20 +139,26 @@ .. py:function:: magnum.trade.AbstractImporter.image1d_name :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `image1d_count` + :raise ValueError: If :p:`id` is negative or not less than + :ref:`image1d_count` .. py:function:: magnum.trade.AbstractImporter.image2d_name :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `image2d_count` + :raise ValueError: If :p:`id` is negative or not less than + :ref:`image2d_count` .. py:function:: magnum.trade.AbstractImporter.image3d_name :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `image3d_count` + :raise ValueError: If :p:`id` is negative or not less than + :ref:`image3d_count` .. py:function:: magnum.trade.AbstractImporter.image1d :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `image1d_count` + :raise ValueError: If :p:`id` is negative or not less than + :ref:`image1d_count` .. py:function:: magnum.trade.AbstractImporter.image2d :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `image2d_count` + :raise ValueError: If :p:`id` is negative or not less than + :ref:`image2d_count` .. py:function:: magnum.trade.AbstractImporter.image3d :raise RuntimeError: If no file is opened - :raise ValueError: If :p:`id` is negative or not less than `image3d_count` + :raise ValueError: If :p:`id` is negative or not less than + :ref:`image3d_count` diff --git a/doc/python/pages/api-conventions.rst b/doc/python/pages/api-conventions.rst index b55b9757..3656a952 100644 --- a/doc/python/pages/api-conventions.rst +++ b/doc/python/pages/api-conventions.rst @@ -52,12 +52,12 @@ useful in a Python setting. .. class:: m-table -=================================== ============================ +=================================== ================================== C++ Python -=================================== ============================ -:dox:`CORRADE_BUILD_MULTITHREADED` `corrade.BUILD_MULTITHREADED` -:dox:`MAGNUM_TARGET_GLES` `magnum.TARGET_GLES` -=================================== ============================ +=================================== ================================== +:dox:`CORRADE_BUILD_MULTITHREADED` :ref:`corrade.BUILD_MULTITHREADED` +:dox:`MAGNUM_TARGET_GLES` :ref:`magnum.TARGET_GLES` +=================================== ================================== `Namespaces / modules`_ ----------------------- @@ -67,8 +67,8 @@ C++ Python =================================== ============================ C++ Python =================================== ============================ -:dox:`Magnum::Math` `magnum.math` -:dox:`Magnum::SceneGraph` `magnum.scenegraph` +:dox:`Magnum::Math` :ref:`magnum.math` +:dox:`Magnum::SceneGraph` :ref:`magnum.scenegraph` =================================== ============================ `Classes`_ @@ -79,8 +79,8 @@ C++ Python =================================== ============================ C++ Python =================================== ============================ -:dox:`Vector2i` `Vector2i` -:dox:`GL::Buffer` `gl.Buffer` +:dox:`Vector2i` :ref:`Vector2i` +:dox:`GL::Buffer` :ref:`gl.Buffer` =================================== ============================ `Functions`_ @@ -91,10 +91,10 @@ C++ Python =============================================================== =========== 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) ` +:dox:`Math::angle()` :ref:`math.angle()` +:dox:`Vector2::xAxis() ` :ref:`Vector2.x_axis()` +:dox:`v.isZero() ` :ref:`v.is_zero() ` +:dox:`m.transformVector(a) ` :ref:`m.transform_vector(a) ` =============================================================== =========== `Enums`_ @@ -105,24 +105,24 @@ C++ Python ============================================== ============================ C++ Python ============================================== ============================ -:dox:`PixelFormat::RGB8Unorm` `PixelFormat.RGB8_UNORM` -:dox:`MeshPrimitive::TriangleStrip` `MeshPrimitive.TRIANGLE_STRIP` +:dox:`PixelFormat::RGB8Unorm` :ref:`PixelFormat.RGB8_UNORM` +:dox:`MeshPrimitive::TriangleStrip` :ref:`MeshPrimitive.TRIANGLE_STRIP` ============================================== ============================ `Constants`_ ------------ Apart from :dox:`Math::Constants`, which are exposed directly as members of the -`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()`. +:ref:`magnum.math` submodule to mimic Python's :ref:`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()`. .. class:: m-table ============================================== ============================ C++ Python ============================================== ============================ -:dox:`Constants::pi() ` `math.pi ` +:dox:`Constants::pi() ` :ref:`math.pi ` :dox:`Math::Vector::Size` :py:`len(vec)` ============================================== ============================ @@ -189,14 +189,14 @@ In particular, both the C++ and the Python API is designed in a way to prevent too generic or confusing names in the root namespace / module and also keeping it relatively clean and small, without too many symbols. On the other hand, the subnamespaces *do* have generic names. The :dox:`GL::version()` / -`gl.version()` API is one example --- it's tucked in a subnamespace so the +:ref:`gl.version()` API is one example --- it's tucked in a subnamespace so the generic name isn't a problem, but you wouldn't find anything of similar genericity in the root namespace / module. An exception to this rule is exposed preprocessor definitions --- these are *not* pulled in when doing :py:`from magnum import *` as this would likely -cause conflicts (in particular, `BUILD_STATIC` is defined by Corrade as well). -Instead, you have to access them like this: +cause conflicts (in particular, :ref:`BUILD_STATIC` is defined by Corrade as +well). Instead, you have to access them like this: .. code:: py @@ -224,9 +224,10 @@ C++ APIs that have alternative implementations (such as typedef SceneGraph::Object Object3D; In Python, the alternate implementations are tucked in submodules (such as -`platform.sdl2` vs. `platform.glfw`, or `scenegraph.matrix` vs. -`scenegraph.trs`), each submodule providing the same names (such as -`Application ` or `Object3D `) +:ref:`platform.sdl2` vs. :ref:`platform.glfw`, or :ref:`scenegraph.matrix` vs. +:ref:`scenegraph.trs`), each submodule providing the same names (such as +:ref:`Application ` or +:ref:`Object3D `) and the designed way to use them is via :py:`from ... import`: .. code:: py diff --git a/doc/python/pages/building.rst b/doc/python/pages/building.rst index 1b01000a..f7443231 100644 --- a/doc/python/pages/building.rst +++ b/doc/python/pages/building.rst @@ -157,9 +157,9 @@ running them is then a matter of: .. block-default:: Disabling GL tests If the tests detect that one of - `platform.WindowlessApplication `\ s is - present, GL tests (suffixed with ``_gl``) will be run as well. In order to - disable them (for example when running on a headless CI), set the + :ref:`platform.WindowlessApplication `\ s + is present, GL tests (suffixed with ``_gl``) will be run as well. In order + to disable them (for example when running on a headless CI), set the :sh:`$MAGNUM_SKIP_GL_TESTS` environment variable to ``ON``: .. code:: sh diff --git a/doc/python/pages/changelog.rst b/doc/python/pages/changelog.rst index 1f6cb777..06863fb7 100644 --- a/doc/python/pages/changelog.rst +++ b/doc/python/pages/changelog.rst @@ -38,20 +38,21 @@ Changelog Released 2020-06-27, tagged as :gh:`v2020.06 `. -- Exposed `Matrix4.cofactor()`, `Matrix4.comatrix()`, `Matrix4.adjugate()` - (and equivalents in other matrix sizes), and `Matrix4.normal_matrix()` -- Exposed `gl.AbstractFramebuffer.blit()` functions and related enums -- Exposed more keys in `platform.sdl2.Application` and - `platform.glfw.Application` -- Exposed `gl.AbstractTexture.unbind()` -- Exposed `trade.AbstractImporter.image2d_level_count()` and related APIs for - 1D and 3D -- Exposed `trade.MeshData` and related APIs, the previous +- Exposed :ref:`Matrix4.cofactor()`, :ref:`Matrix4.comatrix()`, + :ref:`Matrix4.adjugate()` (and equivalents in other matrix sizes), and + :ref:`Matrix4.normal_matrix()` +- Exposed :ref:`gl.AbstractFramebuffer.blit()` functions and related enums +- Exposed more keys in :ref:`platform.sdl2.Application` and + :ref:`platform.glfw.Application` +- Exposed :ref:`gl.AbstractTexture.unbind()` +- Exposed :ref:`trade.AbstractImporter.image2d_level_count()` and related + APIs for 1D and 3D +- Exposed :ref:`trade.MeshData` and related APIs, the previous ``trade.MeshData3D`` APIs are removed -- Exposed new APIs and tangent support in the `primitives` library -- `platform.sdl2.Application` and `platform.glfw.Application` now provide a - clear error instead of "pure virtual method call" in case ``draw_event()`` - is not implemented +- Exposed new APIs and tangent support in the :ref:`primitives` library +- :ref:`platform.sdl2.Application` and :ref:`platform.glfw.Application` now + provide a clear error instead of "pure virtual method call" in case + ``draw_event()`` is not implemented - Library version is now exposed through ``MAGNUMBINDINGS_VERSION_YEAR``, ``MAGNUMBINDINGS_VERSION_MONTH``, ``MAGNUMBINDINGS_VERSION_COMMIT``, ``MAGNUMBINDINGS_VERSION_HASH`` and ``MAGNUMBINDINGS_VERSION_STRING`` diff --git a/doc/python/pages/index.rst b/doc/python/pages/index.rst index 61f3817d..0472d756 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 `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. +See the :ref:`building docs ` for an installation guide, +:ref:`API convention documentation ` and +:ref:`documentation of each module ` for more information about +the actual usage. There are also :ref:`examples ` to give you +an idea about how the API feels. `Contact & support`_ ====================