~cnx/palace

e156f5822754abe7c17275b6e2bbe120aafee368 — Nguyễn Gia Phong 10 months ago 605a2c7
Use PyData Sphinx theme

The documentation structure is reworked to best suit the theme.
6 files changed, 196 insertions(+), 203 deletions(-)

M docs/gitlab-ci.yml
M docs/source/conf.py
M docs/source/contributing.rst
D docs/source/design.rst
M docs/source/index.rst
M setup.cfg
M docs/gitlab-ci.yml => docs/gitlab-ci.yml +1 -1
@@ 9,7 9,7 @@ before_script:
pages:
  stage: deploy
  script:
    - python -m pip install Sphinx sphinx_rtd_theme .
    - python -m pip install Sphinx pydata-sphinx-theme .
    - sphinx-build -bhtml docs/source public
  artifacts:
    paths:

M docs/source/conf.py => docs/source/conf.py +6 -2
@@ 8,7 8,7 @@
project = 'palace'
copyright = '2019, 2020  Nguyễn Gia Phong et al'
author = 'Nguyễn Gia Phong et al.'
release = '0.2.4'
release = '0.2.5'

# Add any Sphinx extension module names here, as strings.
# They can be extensions coming with Sphinx (named 'sphinx.ext.*')


@@ 26,7 26,11 @@ templates_path = []
exclude_patterns = []

# Options for HTML output
html_theme = 'sphinx_rtd_theme'
html_theme = 'pydata_sphinx_theme'
html_theme_options = {'external_links': [
    {'name': 'SourceHut', 'url': 'https://sr.ht/~cnx/palace'},
    {'name': 'PyPI', 'url': 'https://pypi.org/project/palace'},
    {'name': 'Matrix', 'url': 'https://matrix.to/#/#palace-dev:matrix.org'}]}

# Add any paths that contain custom static files (such as style sheets)
# here, relative to this directory.  They are copied after the builtin

M docs/source/contributing.rst => docs/source/contributing.rst +187 -4
@@ 1,6 1,8 @@
Getting Involved
================

.. currentmodule:: palace

First of all, thank you for using and contributing to palace!  We welcome
all forms of contribution, and `the mo the merier`_.  By saying this, we also
mean that we much prefer receiving many small and self-contained bug reports,


@@ 91,11 93,190 @@ to improve the CI/CD may find it helpful.
   Play around with it for a little to make sure that everything is OK.
#. Announce to the `mailing list`_.  With fear and trembling.

Style Guidelines
Coding Standards
----------------

Philosophy
^^^^^^^^^^

In order to write safe, efficient, easy-to-use and extendable Python,
the following principals should be followed.

.. _impl-idiom:

The Impl Idiom
""""""""""""""

*Not to be confused with* `the pimpl idiom`_.

For memory-safety, whenever possible, we rely on Cython for allocation and
deallocation of C++ objects.  To do this, the nullary constructor needs to be
(re-)declared in Cython, e.g.

.. code-block:: cython

   cdef extern from 'foobar.h' namespace 'foobar':
       cdef cppclass Foo:
           Foo()
           float meth(size_t crack) except +
           ...

The Cython extension type can then be declared as follows

.. code-block:: cython

   cdef class Bar:
       cdef Foo impl

       def __init__(self, *args, **kwargs):
           self.impl = ...

       @staticmethod
       def from_baz(baz: Baz) -> Bar:
           bar = Bar.__new__(Bar)
           bar.impl = ...
           return bar

       def meth(self, crack: int) -> float:
           return self.impl.meth(crack)

The Modern Python
"""""""""""""""""

One of the goal of palace is to create a Pythonic, i.e. intuitive and concise,
interface.  To achieve this, we try to make use of some modern Python features,
which not only allow users to adopt palace with ease, but also make their
programs more readable and less error-prone.

.. _getter-setter:

Property Attributes
'''''''''''''''''''

A large proportion of alure API are getters/setter methods.  In Python,
it is a good practice to use property_ to abstract these calls, and thus make
the interface more natural with attribute-like referencing and assignments.

Due to implementation details, Cython has to hijack the ``@property`` decorator
to make it work for read-write properties.  Unfortunately, the Cython-generated
descriptors do not play very well with other builtin decorators, thus in some
cases, it is recommended to alias the call to ``property`` as follows

.. code-block:: python

   getter = property
   setter = lambda fset: property(fset=fset, doc=fset.__doc__)

Then ``@getter`` and ``@setter`` can be used to decorate read-only and
write-only properties, respectively, without any trouble even if other
decorators are used for the same extension type method.

Context Managers
''''''''''''''''

The alure API defines many objects that need manual tear-down in
a particular order.  Instead of trying to be clever and perform automatic
clean-ups at garbage collection, we should put the user in control.
To quote *The Zen of Python*,

   | If the implementation is hard to explain, it's a bad idea.
   | If the implementation is easy to explain, it may be a good idea.

With that being said, it does not mean we do not provide any level of
abstraction.  A simplified case in point would be

.. code-block:: cython

   cdef class Device:
       cdef alure.Device impl

       def __init__(self, name: str = '') -> None:
           self.impl = devmgr.open_playback(name)

       def __enter__(self) -> Device:
           return self

       def __exit__(self, *exc) -> Optional[bool]:
           self.close()

       def close(self) -> None:
           self.impl.close()

Now if the ``with`` statement is used, it will make sure the device
will be closed, regardless of whatever may happen within the inner block

.. code-block:: python

   with Device() as dev:
       ...

as it is equivalent to

.. code-block:: python

   dev = Device()
   try:
       ...
   finally:
       dev.close()

Other than closure/destruction of objects, typical uses of `context managers`__
also include saving and restoring various kinds of global state (as seen in
:py:class:`Context`), locking and unlocking resources, etc.

__ https://docs.python.org/3/reference/datamodel.html#context-managers

The Double Reference
''''''''''''''''''''

While wrapping C++ interfaces, :ref:`the impl idiom <impl-idiom>` might not
be adequate, since the derived Python methods need to be callable from C++.
Luckily, Cython can handle Python objects within C++ classes just fine,
although we'll need to handle the reference count ourselves, e.g.

.. code-block:: cython

   cdef cppclass CppDecoder(alure.BaseDecoder):
       Decoder pyo

       __init__(Decoder decoder):
           this.pyo = decoder
           Py_INCREF(pyo)

       __dealloc__():
           Py_DECREF(pyo)

       bool seek(uint64_t pos):
           return pyo.seek(pos)

With this being done, we can now write the wrapper as simply as

.. code-block:: cython

   cdef class BaseDecoder:
       cdef shared_ptr[alure.Decoder] pimpl

       def __cinit__(self, *args, **kwargs) -> None:
           self.pimpl = shared_ptr[alure.Decoder](new CppDecoder(self))

       def seek(pos: int) -> bool:
           ...

Because ``__cinit__`` is called by ``__new__``, any Python class derived
from ``BaseDecoder`` will be exposed to C++ as an attribute of ``CppDecoder``.
Effectively, this means the users can have the alure API calling their
inherited Python object as naturally as if palace is implemented in pure Python.

In practice, :py:class:`BaseDecoder` will also need to take into account
other guarding mechanisms like :py:class:`abc.ABC`.  Due to Cython limitations,
implementation as a pure Python class and :ref:`aliasing <getter-setter>` of
``@getter``/``@setter`` should be considered.

Style Guidelines
^^^^^^^^^^^^^^^^

Python and Cython
^^^^^^^^^^^^^^^^^
"""""""""""""""""

Generally, palace follows :pep:`8` and :pep:`257`,
with the following preferences and exceptions:


@@ 119,12 300,12 @@ with the following preferences and exceptions:
* Use numpydoc_ markups moderately to keep docstrings readable as plain text.

C++
^^^
"""

C++ codes should follow GNU style, which is best documented at Octave_.

reStructuredText
^^^^^^^^^^^^^^^^
""""""""""""""""

Overall, palace's documentation follows CPython documenting_ style guide,
with a few additional preferences.


@@ 157,6 338,8 @@ except after the final sentence.
.. _tag: https://git-scm.com/docs/git-tag
.. _PyPI: https://pypi.org
.. _twine: https://twine.readthedocs.io
.. _the pimpl idiom: https://wiki.c2.com/?PimplIdiom
.. _property:  https://docs.python.org/3/library/functions.html#property
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
.. _Octave: https://wiki.octave.org/C%2B%2B_style_guide
.. _documenting: https://devguide.python.org/documenting/#style-guide

D docs/source/design.rst => docs/source/design.rst +0 -185
@@ 1,185 0,0 @@
Design Principles
=================

.. currentmodule:: palace

In this section, we will discuss a few design principles in order to write
a safe, efficient, easy-to-use and extendable 3D audio library for Python,
by wrapping existing functionalities from the C++ API alure_.

This part of the documentation assumes its reader are at least familiar with
Cython, Python and C++11.

.. _impl-idiom:

The Impl Idiom
--------------

*Not to be confused with* `the pimpl idiom`_.

For memory-safety, whenever possible, we rely on Cython for allocation and
deallocation of C++ objects.  To do this, the nullary constructor needs to be
(re-)declared in Cython, e.g.

.. code-block:: cython

   cdef extern from 'foobar.h' namespace 'foobar':
       cdef cppclass Foo:
           Foo()
           float meth(size_t crack) except +
           ...

The Cython extension type can then be declared as follows

.. code-block:: cython

   cdef class Bar:
       cdef Foo impl

       def __init__(self, *args, **kwargs):
           self.impl = ...

       @staticmethod
       def from_baz(baz: Baz) -> Bar:
           bar = Bar.__new__(Bar)
           bar.impl = ...
           return bar

       def meth(self, crack: int) -> float:
           return self.impl.meth(crack)

The Modern Python
-----------------

One of the goal of palace is to create a Pythonic, i.e. intuitive and concise,
interface.  To achieve this, we try to make use of some modern Python features,
which not only allow users to adopt palace with ease, but also make their
programs more readable and less error-prone.

.. _getter-setter:

Property Attributes
^^^^^^^^^^^^^^^^^^^

A large proportion of alure API are getters/setter methods.  In Python,
it is a good practice to use property_ to abstract these calls, and thus make
the interface more natural with attribute-like referencing and assignments.

Due to implementation details, Cython has to hijack the ``@property`` decorator
to make it work for read-write properties.  Unfortunately, the Cython-generated
descriptors do not play very well with other builtin decorators, thus in some
cases, it is recommended to alias the call to ``property`` as follows

.. code-block:: python

   getter = property
   setter = lambda fset: property(fset=fset, doc=fset.__doc__)

Then ``@getter`` and ``@setter`` can be used to decorate read-only and
write-only properties, respectively, without any trouble even if other
decorators are used for the same extension type method.

Context Managers
^^^^^^^^^^^^^^^^

The alure API defines many objects that need manual tear-down in
a particular order.  Instead of trying to be clever and perform automatic
clean-ups at garbage collection, we should put the user in control.
To quote *The Zen of Python*,

   | If the implementation is hard to explain, it's a bad idea.
   | If the implementation is easy to explain, it may be a good idea.

With that being said, it does not mean we do not provide any level of
abstraction.  A simplified case in point would be

.. code-block:: cython

   cdef class Device:
       cdef alure.Device impl

       def __init__(self, name: str = '') -> None:
           self.impl = devmgr.open_playback(name)

       def __enter__(self) -> Device:
           return self

       def __exit__(self, *exc) -> Optional[bool]:
           self.close()

       def close(self) -> None:
           self.impl.close()

Now if the ``with`` statement is used, it will make sure the device
will be closed, regardless of whatever may happen within the inner block

.. code-block:: python

   with Device() as dev:
       ...

as it is equivalent to

.. code-block:: python

   dev = Device()
   try:
       ...
   finally:
       dev.close()

Other than closure/destruction of objects, typical uses of `context managers`__
also include saving and restoring various kinds of global state (as seen in
:py:class:`Context`), locking and unlocking resources, etc.

__ https://docs.python.org/3/reference/datamodel.html#context-managers

The Double Reference
--------------------

While wrapping C++ interfaces, :ref:`the impl idiom <impl-idiom>` might not
be adequate, since the derived Python methods need to be callable from C++.
Luckily, Cython can handle Python objects within C++ classes just fine,
although we'll need to handle the reference count ourselves, e.g.

.. code-block:: cython

   cdef cppclass CppDecoder(alure.BaseDecoder):
       Decoder pyo

       __init__(Decoder decoder):
           this.pyo = decoder
           Py_INCREF(pyo)

       __dealloc__():
           Py_DECREF(pyo)

       bool seek(uint64_t pos):
           return pyo.seek(pos)

With this being done, we can now write the wrapper as simply as

.. code-block:: cython

   cdef class BaseDecoder:
       cdef shared_ptr[alure.Decoder] pimpl

       def __cinit__(self, *args, **kwargs) -> None:
           self.pimpl = shared_ptr[alure.Decoder](new CppDecoder(self))

       def seek(pos: int) -> bool:
           ...

Because ``__cinit__`` is called by ``__new__``, any Python class derived
from ``BaseDecoder`` will be exposed to C++ as an attribute of ``CppDecoder``.
Effectively, this means the users can have the alure API calling their
inherited Python object as naturally as if palace is implemented in pure Python.

In practice, :py:class:`BaseDecoder` will also need to take into account
other guarding mechanisms like :py:class:`abc.ABC`.  Due to Cython limitations,
implementation as a pure Python class and :ref:`aliasing <getter-setter>` of
``@getter``/``@setter`` should be considered.

.. _alure: https://github.com/kcat/alure
.. _`the pimpl idiom`: https://wiki.c2.com/?PimplIdiom
.. _property:  https://docs.python.org/3/library/functions.html#property

M docs/source/index.rst => docs/source/index.rst +0 -9
@@ 20,18 20,9 @@ following :pep:`8#naming-conventions` (``PascalCase.snake_case``).
   installation
   tutorial/index
   reference/index
   design
   contributing
   copying

.. toctree::
   :caption: Quick Navigation
   :hidden:

   SourceHut Project <https://sr.ht/~cnx/palace>
   Python Package Index <https://pypi.org/project/palace>
   Matrix Chat Room <https://matrix.to/#/#palace-dev:matrix.org>

Indices and Tables
------------------


M setup.cfg => setup.cfg +2 -2
@@ 1,9 1,9 @@
[metadata]
name = palace
version = 0.2.4
version = 0.2.5
url = https://mcsinyx.gitlab.io/palace
author = Nguyễn Gia Phong
author_email = mcsinyx@disroot.org
author_email = ~cnx/palace@lists.sr.ht
classifiers =
    Development Status :: 4 - Beta
    Intended Audience :: Developers