ic
/
magnum-bindings
6
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

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

pull/8/head
Vladimír Vondruš 7 years ago
parent
52debd42c0
commit
3ceb292c15
9 changed files with 61 additions and 73 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 10
      doc/python/conf.py
  2. 61
      doc/python/magnum.math.rst
  3. 6
      doc/python/magnum.platform.rst
  4. 5
      doc/python/magnum.rst
  5. BIN
      doc/python/numpy.inv
  6. 27
      doc/python/pages/api-conventions.rst
  7. 15
      doc/python/pages/building.rst
  8. 10
      doc/python/pages/index.rst
  9. BIN
      doc/python/python.inv

10
doc/python/conf.py
Unescape View File

@ -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

61
doc/python/magnum.math.rst
Unescape View File

@ -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 <magnum.math.pi>` or
`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.
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`

6
doc/python/magnum.platform.rst
Unescape View File

@ -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

5
doc/python/magnum.rst
Unescape View File

@ -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

BIN
doc/python/numpy.inv
View File

Binary file not shown.

27
doc/python/pages/api-conventions.rst
Unescape View File

@ -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() <Math::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() <Math::Vector2::xAxis()>` `Vector2.x_axis()`
:dox:`v.isZero() <Math::Vector::isZero()>` `v.is_zero() <Vector3.is_zero()>`
: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)`
============================================== ============================

15
doc/python/pages/building.rst
Unescape View File

@ -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
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 <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>`.

10
doc/python/pages/index.rst
Unescape View File

@ -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,
:link-ref:`API convention documentation <api-conventions.html>` and
:link-ref:`documentation of each module <modules.html>` for more information
about the actual usage. There are also :link-ref:`examples <examples.html>` to
give you an idea about how the API feels.
See the `building docs <std:doc:building>` for an installation guide,
`API convention documentation <std:doc:api-conventions>` and
`documentation of each module <std:special:modules>` for more information about
the actual usage. There are also `examples <std:doc:examples>` to give you an
idea about how the API feels.
`Contact & support`_
====================

BIN
doc/python/python.inv
View File

Binary file not shown.
Write Preview
Loading…
Cancel
Save