mirror of https://github.com/McSinyx/palace
Add contributing guidelines and project overview
Co-Authored-By: Ngô Ngọc Đức Huy <duchuy29092000@gmail.com>
This commit is contained in:
parent
625b166261
commit
11cc59fc86
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
|
|
@ -1,4 +1,4 @@
|
|||
# Sphinx build info version 1
|
||||
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
|
||||
config: e4dd2ac7e3904dfb6fca2de3ac852f68
|
||||
config: 2d15f2ac65f2553f6de6e37e9bc0b2bb
|
||||
tags: 645f666f9bcd5a90fca523b33c5a78b7
|
||||
|
|
|
|||
|
|
@ -0,0 +1,203 @@
|
|||
Getting Involved
|
||||
================
|
||||
|
||||
.. note:: The development of palace is carried out on GitHub_.
|
||||
Since GitHub is not free software, we fully understand
|
||||
if one does not want to register an account just to participate
|
||||
in our development. Therefore, we also welcome patches
|
||||
and bug reports sent via email.
|
||||
|
||||
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,
|
||||
feature requests and patches than a giant one. There is no limit for
|
||||
the number of contributions one may or should make. While it may seem
|
||||
appealing to be able to dump all thoughts and feelings into one ticket,
|
||||
it would be more difficult for us to keep track of the progress.
|
||||
|
||||
Reporting a Bug
|
||||
---------------
|
||||
|
||||
Before filing a bug report, please make sure that the bug has not been
|
||||
already reported by searching our GitHub Issues_ tracker.
|
||||
|
||||
To facilitate the debugging process, a bug report should at least contain
|
||||
the following information:
|
||||
|
||||
#. The platform, the CPython version and the compiler used to build it.
|
||||
These can be obtained from :py:func:`platform.platform`,
|
||||
:py:func:`platform.python_version` and :py:func:`platform.python_compiler`,
|
||||
respectively.
|
||||
#. The version of palace and how you installed it.
|
||||
The earlier is usually provided by ``pip show palace``.
|
||||
#. Detailed instructions on how to reproduce the bug,
|
||||
for example a short Python script would be appreciated.
|
||||
|
||||
Requesting a Feature
|
||||
--------------------
|
||||
|
||||
Prior to filing a feature request, please make sure that the feature
|
||||
has not been already reported by searching our GitHub Issues_ tracker.
|
||||
|
||||
Please only ask for features that you (or an incapacitated friend
|
||||
you can personally talk to) require. Do not request features because
|
||||
they seem like a good idea. If they are really useful, they will be
|
||||
requested by someone who requires them.
|
||||
|
||||
Submitting a Patch
|
||||
------------------
|
||||
|
||||
We accept all kinds of patches, from documentation and CI/CD setup
|
||||
to bug fixes, feature implementations and tests. Except for documentation
|
||||
located in the ``gh-pages`` branch, others should be filed against
|
||||
the development branch ``master``. These are hosted on GitHub and
|
||||
one may create a local repository by running::
|
||||
|
||||
git clone https://github.com/McSinyx/palace
|
||||
|
||||
While the patch can be submitted via email, it is preferable to file
|
||||
a pull request on GitHub to allow more people to review it, since we do not
|
||||
have any mail list. Either way, contributors must have legal permission
|
||||
to distribute the code and it must be available under `LGPLv3+`_. Furthermore,
|
||||
each contributor retains the copyrights of their patch, to ensure that
|
||||
the licence can never be revoked even if others wants to. It is advisable
|
||||
that the author list per legal name under the copyright header
|
||||
of each source file they modify, like so::
|
||||
|
||||
Copyright (C) 2038 Foo Bar
|
||||
|
||||
Using GitHub
|
||||
^^^^^^^^^^^^
|
||||
|
||||
#. Create a fork_ of our repository on GitHub.
|
||||
#. Checkout the source code and (optionally) add the ``upstream`` remote::
|
||||
|
||||
git clone https://github.com/YOUR_GITHUB_USERNAME/palace
|
||||
cd palace
|
||||
git remote add upstream https://github.com/McSinyx/palace
|
||||
|
||||
#. Start working on your patch and make sure your code complies with
|
||||
the `Style Guidelines`_ and passes the test suit run by tox_.
|
||||
#. Add relevant tests to the patch and work on it until they all pass.
|
||||
In case one is only modifying tests, perse may install palace using
|
||||
``CYTHON_TRACE=1 pip install .`` then run pytest_ directly to avoid
|
||||
having to build the extension module multiple times.
|
||||
#. Update the copyright notices of the files you modified.
|
||||
Palace is collectively licensed under `LGPLv3+`_,
|
||||
and to protect the freedom of the users,
|
||||
copyright holders need to be properly documented.
|
||||
#. Add_, commit_ with `a great message`_ then push_ the result.
|
||||
#. Finally, `create a pull request`_. We will then review and merge it.
|
||||
|
||||
It is recommended to create a new branch in your fork
|
||||
(``git checkout -c what-you-are-working-on``) instead of working directly
|
||||
on ``master``. This way one can still sync per fork with our ``master`` branch
|
||||
and ``git pull --rebase upstream master`` to avoid integration issues.
|
||||
|
||||
Via Email
|
||||
^^^^^^^^^
|
||||
|
||||
#. Checkout the source code::
|
||||
|
||||
git clone https://github.com/McSinyx/palace
|
||||
cd palace
|
||||
|
||||
#. Work on your patch with tests and copyright notice included
|
||||
as described above.
|
||||
#. `git-format-patch`_ and send it to one of the maintainers
|
||||
(our emails addresses are available under ``git log``).
|
||||
We will then review and merge it.
|
||||
|
||||
In any case, thank you very much for your contributions!
|
||||
|
||||
Making a Release
|
||||
----------------
|
||||
|
||||
While this is meant for developers doing a palace release, contributors wishing
|
||||
to improve the CI/CD may find it helpful.
|
||||
|
||||
#. Under the local repository, checkout the ``master`` branch
|
||||
and sync with the one on GitHub using ``git pull``.
|
||||
#. Bump the version in ``setup.cfg`` and push to GitHub.
|
||||
#. Create a source distribution by running ``setup.py sdist``.
|
||||
The distribution generated by this command is now referred to as ``sdist``.
|
||||
#. Using twine_, upload the ``sdist`` to PyPI via ``twine upload $sdist``.
|
||||
#. On GitHub, tag a new release with the ``sdist`` attached.
|
||||
In the release note, make sure to include all user-facing changes
|
||||
since the previous release. This will trigger the CD services
|
||||
to build the wheels and publish them to PyPI.
|
||||
#. Wait for the wheel for your platform to arrive to PyPI and install it.
|
||||
Play around with it for a little to make sure that everything is OK.
|
||||
#. Under the local repository, checkout the ``gh-pages`` branch.
|
||||
Often, is it necessary to update the credits under the :doc:`copying`
|
||||
section and review if the :doc:`reference` section needs any change
|
||||
before running ``make html`` to rebuild to documentation.
|
||||
#. View the documentation locally then push it to GitHub.
|
||||
|
||||
Style Guidelines
|
||||
----------------
|
||||
|
||||
Python and Cython
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Generally, palace follows :pep:`8` and :pep:`257`,
|
||||
with the following preferences and exceptions:
|
||||
|
||||
* Hanging indentation is *always* preferred,
|
||||
where continuation lines are indented by 4 spaces.
|
||||
* Comments and one-line docstrings are limited to column 79
|
||||
instead of 72 like for multi-line docstrings.
|
||||
* Cython extern declarations need not follow the 79-character limit.
|
||||
* Break long lines before a binary operator.
|
||||
* Use form feeds sparingly to break long modules
|
||||
into pages of relating functions and classes.
|
||||
* Prefer single-quoted strings over double-quoted strings,
|
||||
unless the string contains single quote characters.
|
||||
* Avoid trailing commas at all costs.
|
||||
* Line breaks within comments and docstrings should not cut a phrase in half.
|
||||
* Everything deserves a docstring. Palace follows numpydoc_ which support
|
||||
documenting attributes as well as constants and module-level variables.
|
||||
In additional to docstrings, type annotations should be employed
|
||||
for all public names.
|
||||
* 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
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
In order for reStructuredText to be rendered correctly, the body of
|
||||
constructs beginning with a marker (lists, hyperlink targets, comments, etc.)
|
||||
must be aligned relative to the marker. For this reason, it is convenient
|
||||
to set your editor indentation level to 3 spaces, since most constructs
|
||||
starts with two dots and a space. However, be aware of that bullet items
|
||||
require 2-space alignment and other exceptions.
|
||||
|
||||
Limit all lines to a maximum of 79 characters. Similar to comments
|
||||
and docstrings, phrases should not be broken in the middle.
|
||||
The source code of this guide itself is a good example on how line breaks
|
||||
should be handled. Additionally, two spaces should also be used
|
||||
after a sentence-ending period in multi-sentence paragraph,
|
||||
except after the final sentence.
|
||||
|
||||
.. _GitHub: https://github.com/McSinyx/palace
|
||||
.. _the mo the merier:
|
||||
https://www.phrases.org.uk/meanings/the-more-the-merrier.html
|
||||
.. _Issues: https://github.com/McSinyx/palace/issues
|
||||
.. _LGPLv3+: https://www.gnu.org/licenses/lgpl-3.0.en.html
|
||||
.. _fork: https://github.com/McSinyx/palace/fork
|
||||
.. _tox: https://tox.readthedocs.io/en/latest/
|
||||
.. _pytest: https://docs.pytest.org/en/latest/
|
||||
.. _Add: https://git-scm.com/docs/git-add
|
||||
.. _commit: https://git-scm.com/docs/git-commit
|
||||
.. _a great message: https://chris.beams.io/posts/git-commit/#seven-rules
|
||||
.. _push: https://git-scm.com/docs/git-push
|
||||
.. _create a pull request:
|
||||
https://help.github.com/articles/creating-a-pull-request
|
||||
.. _git-format-patch: https://git-scm.com/docs/git-format-patch
|
||||
.. _twine: https://twine.readthedocs.io/en/latest/
|
||||
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
|
||||
.. _Octave: https://wiki.octave.org/C%2B%2B_style_guide
|
||||
|
|
@ -1,6 +1,12 @@
|
|||
Copying
|
||||
=======
|
||||
|
||||
This listing is our best-faith, hard-work effort at accurate attribution,
|
||||
sources, and licenses for everything in palace. If you discover
|
||||
an asset/contribution that is incorrectly attributed or licensed,
|
||||
please contact us immediately. We are happy to do everything we can
|
||||
to fix or remove the issue.
|
||||
|
||||
License
|
||||
-------
|
||||
Palace is free software: you can redistribute it and/or modify it
|
||||
|
|
@ -8,24 +14,18 @@ under the terms of the `GNU Lesser General Public License`_
|
|||
as published by the Free Software Foundation, either version 3
|
||||
of the License, or (at your option) any later version.
|
||||
|
||||
.. _GNU Lesser General Public License:
|
||||
https://www.gnu.org/licenses/lgpl-3.0.en.html
|
||||
|
||||
Credits
|
||||
-------
|
||||
|
||||
To ensure that palace can run without any dependencies outside of the `pip`_
|
||||
To ensure that palace can run without any dependencies outside of the pip_
|
||||
toolchain, the wheels are bundled with dynamically linked libraries from
|
||||
the build machine, which is similar to static linking:
|
||||
|
||||
============== ============
|
||||
Library License
|
||||
============== ============
|
||||
`Alure`_ ZLib
|
||||
Alure_ ZLib
|
||||
`OpenAL Soft`_ GNU LGPLv2+
|
||||
`Vorbis`_ 3-clause BSD
|
||||
`Opus`_ 3-clause BSD
|
||||
`libsndfile`_ GNU LGPL2.1+
|
||||
Vorbis_ 3-clause BSD
|
||||
Opus_ 3-clause BSD
|
||||
libsndfile_ GNU LGPL2.1+
|
||||
============== ============
|
||||
|
||||
In addition, the following sounds are used for testing:
|
||||
|
|
@ -40,6 +40,22 @@ Sound (located in ``tests/data``) License
|
|||
`99642__jobro__deconvoluted-20hz-to-20khz.wav`_ CC BY 3.0
|
||||
=============================================== =========
|
||||
|
||||
Credits
|
||||
-------
|
||||
|
||||
Palace would never have seen the light of day without the help from
|
||||
the developers of Alure_ and Cython_ who promptly gave detail answers
|
||||
and made quick fixes to all of our problems.
|
||||
|
||||
The wheels are build using cibuildwheel_, which made building extension modules
|
||||
much less of a painful experience. `Travis CI`_ and AppVeyor_ kindly provides
|
||||
their services free of charge for automated CI/CD.
|
||||
|
||||
This documentation is generated using Sphinx_, whose maintainer responses
|
||||
extreamly quickly to obsolete Cython-related issues.
|
||||
|
||||
.. _GNU Lesser General Public License:
|
||||
https://www.gnu.org/licenses/lgpl-3.0.en.html
|
||||
.. _pip: https://pip.pypa.io/en/latest/
|
||||
.. _Alure: https://github.com/kcat/alure
|
||||
.. _OpenAL Soft: https://kcat.strangesoft.net/openal.html
|
||||
|
|
@ -51,3 +67,8 @@ Sound (located in ``tests/data``) License
|
|||
.. _261590__kwahmah-02__little-glitch.flac: https://freesound.org/s/261590/
|
||||
.. _353684__tec-studio__drip2.mp3: https://freesound.org/s/353684/
|
||||
.. _99642__jobro__deconvoluted-20hz-to-20khz.wav: https://freesound.org/s/99642/
|
||||
.. _Cython: https://cython.org/
|
||||
.. _cibuildwheel: https://cibuildwheel.readthedocs.io/en/stable/
|
||||
.. _Sphinx: https://www.sphinx-doc.org/en/master/
|
||||
.. _Travis CI: https://travis-ci.com/
|
||||
.. _AppVeyor: https://www.appveyor.com/
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ 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.
|
||||
|
||||
.. _alure: https://github.com/kcat/alure
|
||||
|
||||
.. _impl-idiom:
|
||||
|
||||
The Impl Idiom
|
||||
|
|
@ -48,8 +46,6 @@ The Cython extension type can then be declared as follows
|
|||
def meth(self, crack: int) -> float:
|
||||
return self.impl.meth(crack)
|
||||
|
||||
.. _`the pimpl idiom`: https://wiki.c2.com/?PimplIdiom
|
||||
|
||||
The Modern Python
|
||||
-----------------
|
||||
|
||||
|
|
@ -81,8 +77,6 @@ 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.
|
||||
|
||||
.. _property: https://docs.python.org/3/library/functions.html#property
|
||||
|
||||
Context Managers
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -183,3 +177,7 @@ In practice, :py:class:`palace.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
|
||||
|
|
|
|||
|
|
@ -1,13 +1,20 @@
|
|||
Welcome to our palace!
|
||||
======================
|
||||
|
||||
Pythonic Audio Library and Codecs Environment provides common higher-level API
|
||||
for audio rendering using OpenAL. It wraps around the C++ interface alure_
|
||||
for 3D positional rendering, environmental effects and out-of-the-box
|
||||
codec support, while using Cython to provide a modern interface with
|
||||
type hinting, data descriptors, context managers and ``snake_case``
|
||||
for a safe, convenient and pleasurable experience.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
installation
|
||||
reference
|
||||
design
|
||||
contributing
|
||||
copying
|
||||
|
||||
|
||||
|
|
@ -17,3 +24,5 @@ Indices and tables
|
|||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
.. _alure: https://github.com/kcat/alure
|
||||
|
|
|
|||
|
|
@ -4,9 +4,8 @@ Installation
|
|||
Prerequisites
|
||||
-------------
|
||||
|
||||
Palace requires Python 3.6 for runtime and `pip`_ for installation.
|
||||
|
||||
.. _pip: https://pip.pypa.io/en/latest/
|
||||
Palace requires CPython_ version 3.6 or above for runtime
|
||||
and pip_ for installation.
|
||||
|
||||
Via PyPI
|
||||
--------
|
||||
|
|
@ -16,23 +15,23 @@ Palace can be installed from PyPI::
|
|||
pip install palace
|
||||
|
||||
Wheel distributions are built exclusively for amd64. Currently, only GNU/Linux
|
||||
is properly supported. If you want to help packaging for Windows and macOS,
|
||||
see `GH-1`_ and `GH-63`_ respectively on our issues tracker on GitHub.
|
||||
|
||||
.. _GH-1: https://github.com/McSinyx/palace/issues/1
|
||||
.. _GH-63: https://github.com/McSinyx/palace/issues/63
|
||||
and macOS are properly supported. If you want to help packaging for Windows,
|
||||
please see `GH-1`_ on our issues tracker on GitHub.
|
||||
|
||||
From source
|
||||
-----------
|
||||
|
||||
Aside from the build dependencies listed in ``pyproject.toml``,
|
||||
one will additionally need compatible Python headers, `alure`_,
|
||||
a C++14 compiler, CMake 2.6+ (and probably ``git`` for fetching the source).
|
||||
Palace can then be compiled and installed by running:
|
||||
|
||||
.. code-block:: sh
|
||||
one will additionally need compatible Python headers, alure_,
|
||||
a C++14 compiler, CMake_ 2.6+ (and probably git_ for fetching the source).
|
||||
Palace can then be compiled and installed by running::
|
||||
|
||||
git clone https://github.com/McSinyx/palace.git
|
||||
pip install palace/
|
||||
|
||||
.. _CPython: https://www.python.org/
|
||||
.. _pip: https://pip.pypa.io/en/latest/
|
||||
.. _GH-1: https://github.com/McSinyx/palace/issues/1
|
||||
.. _alure: https://github.com/kcat/alure
|
||||
.. _CMake: https://cmake.org/
|
||||
.. _git: https://git-scm.com/
|
||||
|
|
|
|||
|
|
@ -112,6 +112,10 @@ Sources & Source Groups
|
|||
Environmental Effects
|
||||
---------------------
|
||||
|
||||
For the sake of brevity, we only document the constraints of each effect's
|
||||
properties. Further details can be found at OpenAL's `Effect Extension Guide`_
|
||||
which specifies the purpose and usage of each value.
|
||||
|
||||
.. data:: reverb_preset_names
|
||||
:type: Tuple[str, ...]
|
||||
|
||||
|
|
@ -122,7 +126,6 @@ Environmental Effects
|
|||
|
||||
.. autoclass:: ReverbEffect
|
||||
:members:
|
||||
:undoc-members:
|
||||
|
||||
.. autoclass:: ChorusEffect
|
||||
:members:
|
||||
|
|
@ -170,3 +173,6 @@ File I/O Interface
|
|||
|
||||
.. autoclass:: FileIO
|
||||
:members:
|
||||
|
||||
.. _Effect Extension Guide:
|
||||
https://kcat.strangesoft.net/misc-downloads/Effects%20Extension%20Guide.pdf
|
||||
|
|
|
|||
|
|
@ -1,10 +1,11 @@
|
|||
var DOCUMENTATION_OPTIONS = {
|
||||
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
|
||||
VERSION: '0.1.5',
|
||||
VERSION: '0.2.0',
|
||||
LANGUAGE: 'None',
|
||||
COLLAPSE_INDEX: false,
|
||||
BUILDER: 'html',
|
||||
FILE_SUFFIX: '.html',
|
||||
LINK_SUFFIX: '.html',
|
||||
HAS_SOURCE: true,
|
||||
SOURCELINK_SUFFIX: '.txt',
|
||||
NAVIGATION_WITH_KEYS: false
|
||||
|
|
|
|||
|
|
@ -251,6 +251,7 @@ var Search = {
|
|||
var item = results.pop();
|
||||
var listItem = $('<li style="display:none"></li>');
|
||||
var requestUrl = "";
|
||||
var linkUrl = "";
|
||||
if (DOCUMENTATION_OPTIONS.BUILDER === 'dirhtml') {
|
||||
// dirhtml builder
|
||||
var dirname = item[0] + '/';
|
||||
|
|
@ -260,13 +261,15 @@ var Search = {
|
|||
dirname = '';
|
||||
}
|
||||
requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + dirname;
|
||||
linkUrl = requestUrl;
|
||||
|
||||
} else {
|
||||
// normal html builders
|
||||
requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX;
|
||||
linkUrl = item[0] + DOCUMENTATION_OPTIONS.LINK_SUFFIX;
|
||||
}
|
||||
listItem.append($('<a/>').attr('href',
|
||||
requestUrl +
|
||||
linkUrl +
|
||||
highlightstring + item[2]).html(item[1]));
|
||||
if (item[3]) {
|
||||
listItem.append($('<span> (' + item[3] + ')</span>'));
|
||||
|
|
|
|||
|
|
@ -0,0 +1,295 @@
|
|||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Getting Involved — palace 0.2.0 documentation</title>
|
||||
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||||
<script src="_static/jquery.js"></script>
|
||||
<script src="_static/underscore.js"></script>
|
||||
<script src="_static/doctools.js"></script>
|
||||
<script src="_static/language_data.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Copying" href="copying.html" />
|
||||
<link rel="prev" title="Design Principles" href="design.html" />
|
||||
|
||||
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
|
||||
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
|
||||
|
||||
</head><body>
|
||||
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
|
||||
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="getting-involved">
|
||||
<h1>Getting Involved<a class="headerlink" href="#getting-involved" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The development of palace is carried out on <a class="reference external" href="https://github.com/McSinyx/palace">GitHub</a>.
|
||||
Since GitHub is not free software, we fully understand
|
||||
if one does not want to register an account just to participate
|
||||
in our development. Therefore, we also welcome patches
|
||||
and bug reports sent via email.</p>
|
||||
</div>
|
||||
<p>First of all, thank you for using and contributing to palace! We welcome
|
||||
all forms of contribution, and <a class="reference external" href="https://www.phrases.org.uk/meanings/the-more-the-merrier.html">the mo the merier</a>. By saying this, we also
|
||||
mean that we much prefer receiving many small and self-contained bug reports,
|
||||
feature requests and patches than a giant one. There is no limit for
|
||||
the number of contributions one may or should make. While it may seem
|
||||
appealing to be able to dump all thoughts and feelings into one ticket,
|
||||
it would be more difficult for us to keep track of the progress.</p>
|
||||
<div class="section" id="reporting-a-bug">
|
||||
<h2>Reporting a Bug<a class="headerlink" href="#reporting-a-bug" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Before filing a bug report, please make sure that the bug has not been
|
||||
already reported by searching our GitHub <a class="reference external" href="https://github.com/McSinyx/palace/issues">Issues</a> tracker.</p>
|
||||
<p>To facilitate the debugging process, a bug report should at least contain
|
||||
the following information:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>The platform, the CPython version and the compiler used to build it.
|
||||
These can be obtained from <code class="xref py py-func docutils literal notranslate"><span class="pre">platform.platform()</span></code>,
|
||||
<code class="xref py py-func docutils literal notranslate"><span class="pre">platform.python_version()</span></code> and <code class="xref py py-func docutils literal notranslate"><span class="pre">platform.python_compiler()</span></code>,
|
||||
respectively.</p></li>
|
||||
<li><p>The version of palace and how you installed it.
|
||||
The earlier is usually provided by <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">show</span> <span class="pre">palace</span></code>.</p></li>
|
||||
<li><p>Detailed instructions on how to reproduce the bug,
|
||||
for example a short Python script would be appreciated.</p></li>
|
||||
</ol>
|
||||
</div>
|
||||
<div class="section" id="requesting-a-feature">
|
||||
<h2>Requesting a Feature<a class="headerlink" href="#requesting-a-feature" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Prior to filing a feature request, please make sure that the feature
|
||||
has not been already reported by searching our GitHub <a class="reference external" href="https://github.com/McSinyx/palace/issues">Issues</a> tracker.</p>
|
||||
<p>Please only ask for features that you (or an incapacitated friend
|
||||
you can personally talk to) require. Do not request features because
|
||||
they seem like a good idea. If they are really useful, they will be
|
||||
requested by someone who requires them.</p>
|
||||
</div>
|
||||
<div class="section" id="submitting-a-patch">
|
||||
<h2>Submitting a Patch<a class="headerlink" href="#submitting-a-patch" title="Permalink to this headline">¶</a></h2>
|
||||
<p>We accept all kinds of patches, from documentation and CI/CD setup
|
||||
to bug fixes, feature implementations and tests. Except for documentation
|
||||
located in the <code class="docutils literal notranslate"><span class="pre">gh-pages</span></code> branch, others should be filed against
|
||||
the development branch <code class="docutils literal notranslate"><span class="pre">master</span></code>. These are hosted on GitHub and
|
||||
one may create a local repository by running:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">McSinyx</span><span class="o">/</span><span class="n">palace</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>While the patch can be submitted via email, it is preferable to file
|
||||
a pull request on GitHub to allow more people to review it, since we do not
|
||||
have any mail list. Either way, contributors must have legal permission
|
||||
to distribute the code and it must be available under <a class="reference external" href="https://www.gnu.org/licenses/lgpl-3.0.en.html">LGPLv3+</a>. Furthermore,
|
||||
each contributor retains the copyrights of their patch, to ensure that
|
||||
the licence can never be revoked even if others wants to. It is advisable
|
||||
that the author list per legal name under the copyright header
|
||||
of each source file they modify, like so:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Copyright</span> <span class="p">(</span><span class="n">C</span><span class="p">)</span> <span class="mi">2038</span> <span class="n">Foo</span> <span class="n">Bar</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="section" id="using-github">
|
||||
<h3>Using GitHub<a class="headerlink" href="#using-github" title="Permalink to this headline">¶</a></h3>
|
||||
<ol class="arabic">
|
||||
<li><p>Create a <a class="reference external" href="https://github.com/McSinyx/palace/fork">fork</a> of our repository on GitHub.</p></li>
|
||||
<li><p>Checkout the source code and (optionally) add the <code class="docutils literal notranslate"><span class="pre">upstream</span></code> remote:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">YOUR_GITHUB_USERNAME</span><span class="o">/</span><span class="n">palace</span>
|
||||
<span class="n">cd</span> <span class="n">palace</span>
|
||||
<span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">upstream</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">McSinyx</span><span class="o">/</span><span class="n">palace</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>Start working on your patch and make sure your code complies with
|
||||
the <a class="reference internal" href="#style-guidelines">Style Guidelines</a> and passes the test suit run by <a class="reference external" href="https://tox.readthedocs.io/en/latest/">tox</a>.</p></li>
|
||||
<li><p>Add relevant tests to the patch and work on it until they all pass.
|
||||
In case one is only modifying tests, perse may install palace using
|
||||
<code class="docutils literal notranslate"><span class="pre">CYTHON_TRACE=1</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre">.</span></code> then run <a class="reference external" href="https://docs.pytest.org/en/latest/">pytest</a> directly to avoid
|
||||
having to build the extension module multiple times.</p></li>
|
||||
<li><p>Update the copyright notices of the files you modified.
|
||||
Palace is collectively licensed under <a class="reference external" href="https://www.gnu.org/licenses/lgpl-3.0.en.html">LGPLv3+</a>,
|
||||
and to protect the freedom of the users,
|
||||
copyright holders need to be properly documented.</p></li>
|
||||
<li><p><a class="reference external" href="https://git-scm.com/docs/git-add">Add</a>, <a class="reference external" href="https://git-scm.com/docs/git-commit">commit</a> with <a class="reference external" href="https://chris.beams.io/posts/git-commit/#seven-rules">a great message</a> then <a class="reference external" href="https://git-scm.com/docs/git-push">push</a> the result.</p></li>
|
||||
<li><p>Finally, <a class="reference external" href="https://help.github.com/articles/creating-a-pull-request">create a pull request</a>. We will then review and merge it.</p></li>
|
||||
</ol>
|
||||
<p>It is recommended to create a new branch in your fork
|
||||
(<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">-c</span> <span class="pre">what-you-are-working-on</span></code>) instead of working directly
|
||||
on <code class="docutils literal notranslate"><span class="pre">master</span></code>. This way one can still sync per fork with our <code class="docutils literal notranslate"><span class="pre">master</span></code> branch
|
||||
and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span> <span class="pre">--rebase</span> <span class="pre">upstream</span> <span class="pre">master</span></code> to avoid integration issues.</p>
|
||||
</div>
|
||||
<div class="section" id="via-email">
|
||||
<h3>Via Email<a class="headerlink" href="#via-email" title="Permalink to this headline">¶</a></h3>
|
||||
<ol class="arabic">
|
||||
<li><p>Checkout the source code:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">McSinyx</span><span class="o">/</span><span class="n">palace</span>
|
||||
<span class="n">cd</span> <span class="n">palace</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>Work on your patch with tests and copyright notice included
|
||||
as described above.</p></li>
|
||||
<li><p><a class="reference external" href="https://git-scm.com/docs/git-format-patch">git-format-patch</a> and send it to one of the maintainers
|
||||
(our emails addresses are available under <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code>).
|
||||
We will then review and merge it.</p></li>
|
||||
</ol>
|
||||
<p>In any case, thank you very much for your contributions!</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="making-a-release">
|
||||
<h2>Making a Release<a class="headerlink" href="#making-a-release" title="Permalink to this headline">¶</a></h2>
|
||||
<p>While this is meant for developers doing a palace release, contributors wishing
|
||||
to improve the CI/CD may find it helpful.</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>Under the local repository, checkout the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch
|
||||
and sync with the one on GitHub using <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code>.</p></li>
|
||||
<li><p>Bump the version in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> and push to GitHub.</p></li>
|
||||
<li><p>Create a source distribution by running <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">sdist</span></code>.
|
||||
The distribution generated by this command is now referred to as <code class="docutils literal notranslate"><span class="pre">sdist</span></code>.</p></li>
|
||||
<li><p>Using <a class="reference external" href="https://twine.readthedocs.io/en/latest/">twine</a>, upload the <code class="docutils literal notranslate"><span class="pre">sdist</span></code> to PyPI via <code class="docutils literal notranslate"><span class="pre">twine</span> <span class="pre">upload</span> <span class="pre">$sdist</span></code>.</p></li>
|
||||
<li><p>On GitHub, tag a new release with the <code class="docutils literal notranslate"><span class="pre">sdist</span></code> attached.
|
||||
In the release note, make sure to include all user-facing changes
|
||||
since the previous release. This will trigger the CD services
|
||||
to build the wheels and publish them to PyPI.</p></li>
|
||||
<li><p>Wait for the wheel for your platform to arrive to PyPI and install it.
|
||||
Play around with it for a little to make sure that everything is OK.</p></li>
|
||||
<li><p>Under the local repository, checkout the <code class="docutils literal notranslate"><span class="pre">gh-pages</span></code> branch.
|
||||
Often, is it necessary to update the credits under the <a class="reference internal" href="copying.html"><span class="doc">Copying</span></a>
|
||||
section and review if the <a class="reference internal" href="reference.html"><span class="doc">Reference</span></a> section needs any change
|
||||
before running <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> to rebuild to documentation.</p></li>
|
||||
<li><p>View the documentation locally then push it to GitHub.</p></li>
|
||||
</ol>
|
||||
</div>
|
||||
<div class="section" id="style-guidelines">
|
||||
<h2>Style Guidelines<a class="headerlink" href="#style-guidelines" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="section" id="python-and-cython">
|
||||
<h3>Python and Cython<a class="headerlink" href="#python-and-cython" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Generally, palace follows <span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0008"><strong>PEP 8</strong></a> and <span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0257"><strong>PEP 257</strong></a>,
|
||||
with the following preferences and exceptions:</p>
|
||||
<ul class="simple">
|
||||
<li><p>Hanging indentation is <em>always</em> preferred,
|
||||
where continuation lines are indented by 4 spaces.</p></li>
|
||||
<li><p>Comments and one-line docstrings are limited to column 79
|
||||
instead of 72 like for multi-line docstrings.</p></li>
|
||||
<li><p>Cython extern declarations need not follow the 79-character limit.</p></li>
|
||||
<li><p>Break long lines before a binary operator.</p></li>
|
||||
<li><p>Use form feeds sparingly to break long modules
|
||||
into pages of relating functions and classes.</p></li>
|
||||
<li><p>Prefer single-quoted strings over double-quoted strings,
|
||||
unless the string contains single quote characters.</p></li>
|
||||
<li><p>Avoid trailing commas at all costs.</p></li>
|
||||
<li><p>Line breaks within comments and docstrings should not cut a phrase in half.</p></li>
|
||||
<li><p>Everything deserves a docstring. Palace follows <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc</a> which support
|
||||
documenting attributes as well as constants and module-level variables.
|
||||
In additional to docstrings, type annotations should be employed
|
||||
for all public names.</p></li>
|
||||
<li><p>Use <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc</a> markups moderately to keep docstrings readable as plain text.</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="c">
|
||||
<h3>C++<a class="headerlink" href="#c" title="Permalink to this headline">¶</a></h3>
|
||||
<p>C++ codes should follow GNU style, which is best documented at <a class="reference external" href="https://wiki.octave.org/C%2B%2B_style_guide">Octave</a>.</p>
|
||||
</div>
|
||||
<div class="section" id="restructuredtext">
|
||||
<h3>reStructuredText<a class="headerlink" href="#restructuredtext" title="Permalink to this headline">¶</a></h3>
|
||||
<p>In order for reStructuredText to be rendered correctly, the body of
|
||||
constructs beginning with a marker (lists, hyperlink targets, comments, etc.)
|
||||
must be aligned relative to the marker. For this reason, it is convenient
|
||||
to set your editor indentation level to 3 spaces, since most constructs
|
||||
starts with two dots and a space. However, be aware of that bullet items
|
||||
require 2-space alignment and other exceptions.</p>
|
||||
<p>Limit all lines to a maximum of 79 characters. Similar to comments
|
||||
and docstrings, phrases should not be broken in the middle.
|
||||
The source code of this guide itself is a good example on how line breaks
|
||||
should be handled. Additionally, two spaces should also be used
|
||||
after a sentence-ending period in multi-sentence paragraph,
|
||||
except after the final sentence.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h3><a href="index.html">Table of Contents</a></h3>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="design.html">Design Principles</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Getting Involved</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#reporting-a-bug">Reporting a Bug</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#requesting-a-feature">Requesting a Feature</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#submitting-a-patch">Submitting a Patch</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#making-a-release">Making a Release</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#style-guidelines">Style Guidelines</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="copying.html">Copying</a></li>
|
||||
</ul>
|
||||
<h3>Quick Navigation</h3>
|
||||
<ul>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://pypi.org/project/palace/">
|
||||
Python Package Index
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://travis-ci.com/github/McSinyx/palace">
|
||||
Travis CI Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://ci.appveyor.com/project/McSinyx/palace">
|
||||
AppVeyor Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://github.com/McSinyx/palace">
|
||||
GitHub Repository
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
<div id="searchbox" style="display: none" role="search">
|
||||
<h3 id="searchlabel">Quick search</h3>
|
||||
<div class="searchformwrapper">
|
||||
<form class="search" action="search.html" method="get">
|
||||
<input type="text" name="q" aria-labelledby="searchlabel" />
|
||||
<input type="submit" value="Go" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
<script>$('#searchbox').show(0);</script>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="footer">
|
||||
©2019, 2020 Nguyễn Gia Phong et al.
|
||||
|
||||
|
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.1</a>
|
||||
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
||||
|
||||
|
|
||||
<a href="_sources/contributing.rst.txt"
|
||||
rel="nofollow">Page source</a>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,10 +1,10 @@
|
|||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Copying — palace 0.1.5 documentation</title>
|
||||
<title>Copying — palace 0.2.0 documentation</title>
|
||||
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||||
|
|
@ -14,7 +14,7 @@
|
|||
<script src="_static/language_data.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="prev" title="Design Principles" href="design.html" />
|
||||
<link rel="prev" title="Getting Involved" href="contributing.html" />
|
||||
|
||||
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
|
||||
|
||||
|
|
@ -33,15 +33,17 @@
|
|||
|
||||
<div class="section" id="copying">
|
||||
<h1>Copying<a class="headerlink" href="#copying" title="Permalink to this headline">¶</a></h1>
|
||||
<p>This listing is our best-faith, hard-work effort at accurate attribution,
|
||||
sources, and licenses for everything in palace. If you discover
|
||||
an asset/contribution that is incorrectly attributed or licensed,
|
||||
please contact us immediately. We are happy to do everything we can
|
||||
to fix or remove the issue.</p>
|
||||
<div class="section" id="license">
|
||||
<h2>License<a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Palace is free software: you can redistribute it and/or modify it
|
||||
under the terms of the <a class="reference external" href="https://www.gnu.org/licenses/lgpl-3.0.en.html">GNU Lesser General Public License</a>
|
||||
as published by the Free Software Foundation, either version 3
|
||||
of the License, or (at your option) any later version.</p>
|
||||
</div>
|
||||
<div class="section" id="credits">
|
||||
<h2>Credits<a class="headerlink" href="#credits" title="Permalink to this headline">¶</a></h2>
|
||||
<p>To ensure that palace can run without any dependencies outside of the <a class="reference external" href="https://pip.pypa.io/en/latest/">pip</a>
|
||||
toolchain, the wheels are bundled with dynamically linked libraries from
|
||||
the build machine, which is similar to static linking:</p>
|
||||
|
|
@ -103,6 +105,17 @@ the build machine, which is similar to static linking:</p>
|
|||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<div class="section" id="credits">
|
||||
<h2>Credits<a class="headerlink" href="#credits" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Palace would never have seen the light of day without the help from
|
||||
the developers of <a class="reference external" href="https://github.com/kcat/alure">Alure</a> and <a class="reference external" href="https://cython.org/">Cython</a> who promptly gave detail answers
|
||||
and made quick fixes to all of our problems.</p>
|
||||
<p>The wheels are build using <a class="reference external" href="https://cibuildwheel.readthedocs.io/en/stable/">cibuildwheel</a>, which made building extension modules
|
||||
much less of a painful experience. <a class="reference external" href="https://travis-ci.com/">Travis CI</a> and <a class="reference external" href="https://www.appveyor.com/">AppVeyor</a> kindly provides
|
||||
their services free of charge for automated CI/CD.</p>
|
||||
<p>This documentation is generated using <a class="reference external" href="https://www.sphinx-doc.org/en/master/">Sphinx</a>, whose maintainer responses
|
||||
extreamly quickly to obsolete Cython-related issues.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
|
|
@ -112,36 +125,43 @@ the build machine, which is similar to static linking:</p>
|
|||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h1 class="logo"><a href="index.html">palace</a></h1>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<h3>Navigation</h3>
|
||||
<p class="caption"><span class="caption-text">Contents:</span></p>
|
||||
<h3><a href="index.html">Table of Contents</a></h3>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="design.html">Design Principles</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Getting Involved</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Copying</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#license">License</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#credits">Credits</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<div class="relations">
|
||||
<h3>Related Topics</h3>
|
||||
<h3>Quick Navigation</h3>
|
||||
<ul>
|
||||
<li><a href="index.html">Documentation overview</a><ul>
|
||||
<li>Previous: <a href="design.html" title="previous chapter">Design Principles</a></li>
|
||||
</ul></li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://pypi.org/project/palace/">
|
||||
Python Package Index
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://travis-ci.com/github/McSinyx/palace">
|
||||
Travis CI Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://ci.appveyor.com/project/McSinyx/palace">
|
||||
AppVeyor Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://github.com/McSinyx/palace">
|
||||
GitHub Repository
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div id="searchbox" style="display: none" role="search">
|
||||
<h3 id="searchlabel">Quick search</h3>
|
||||
<div class="searchformwrapper">
|
||||
|
|
@ -152,14 +172,6 @@ the build machine, which is similar to static linking:</p>
|
|||
</div>
|
||||
</div>
|
||||
<script>$('#searchbox').show(0);</script>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
|
|
@ -168,7 +180,7 @@ the build machine, which is similar to static linking:</p>
|
|||
©2019, 2020 Nguyễn Gia Phong et al.
|
||||
|
||||
|
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.1</a>
|
||||
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
||||
|
||||
|
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Design Principles — palace 0.1.5 documentation</title>
|
||||
<title>Design Principles — palace 0.2.0 documentation</title>
|
||||
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||||
|
|
@ -14,7 +14,7 @@
|
|||
<script src="_static/language_data.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Copying" href="copying.html" />
|
||||
<link rel="next" title="Getting Involved" href="contributing.html" />
|
||||
<link rel="prev" title="Reference" href="reference.html" />
|
||||
|
||||
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
|
||||
|
|
@ -191,17 +191,7 @@ implementation as a pure Python class and <a class="reference internal" href="#g
|
|||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h1 class="logo"><a href="index.html">palace</a></h1>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<h3>Navigation</h3>
|
||||
<p class="caption"><span class="caption-text">Contents:</span></p>
|
||||
<h3><a href="index.html">Table of Contents</a></h3>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a></li>
|
||||
|
|
@ -211,18 +201,34 @@ implementation as a pure Python class and <a class="reference internal" href="#g
|
|||
<li class="toctree-l2"><a class="reference internal" href="#the-double-reference">The Double Reference</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Getting Involved</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="copying.html">Copying</a></li>
|
||||
</ul>
|
||||
|
||||
<div class="relations">
|
||||
<h3>Related Topics</h3>
|
||||
<h3>Quick Navigation</h3>
|
||||
<ul>
|
||||
<li><a href="index.html">Documentation overview</a><ul>
|
||||
<li>Previous: <a href="reference.html" title="previous chapter">Reference</a></li>
|
||||
<li>Next: <a href="copying.html" title="next chapter">Copying</a></li>
|
||||
</ul></li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://pypi.org/project/palace/">
|
||||
Python Package Index
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://travis-ci.com/github/McSinyx/palace">
|
||||
Travis CI Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://ci.appveyor.com/project/McSinyx/palace">
|
||||
AppVeyor Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://github.com/McSinyx/palace">
|
||||
GitHub Repository
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div id="searchbox" style="display: none" role="search">
|
||||
<h3 id="searchlabel">Quick search</h3>
|
||||
<div class="searchformwrapper">
|
||||
|
|
@ -233,14 +239,6 @@ implementation as a pure Python class and <a class="reference internal" href="#g
|
|||
</div>
|
||||
</div>
|
||||
<script>$('#searchbox').show(0);</script>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
|
|
@ -249,7 +247,7 @@ implementation as a pure Python class and <a class="reference internal" href="#g
|
|||
©2019, 2020 Nguyễn Gia Phong et al.
|
||||
|
||||
|
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.1</a>
|
||||
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
||||
|
||||
|
|
||||
|
|
|
|||
|
|
@ -2,10 +2,10 @@
|
|||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Index — palace 0.1.5 documentation</title>
|
||||
<title>Index — palace 0.2.0 documentation</title>
|
||||
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||||
|
|
@ -89,7 +89,7 @@
|
|||
</li>
|
||||
<li><a href="reference.html#palace.Buffer">Buffer (class in palace)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.MessageHandler.buffer_loading">buffer_loading (palace.MessageHandler attribute)</a>
|
||||
<li><a href="reference.html#palace.MessageHandler.buffer_loading">buffer_loading() (palace.MessageHandler method)</a>
|
||||
</li>
|
||||
</ul></td>
|
||||
</tr></table>
|
||||
|
|
@ -117,10 +117,10 @@
|
|||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Device.clock_time">clock_time() (palace.Device property)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Device.close">close (palace.Device attribute)</a>
|
||||
<li><a href="reference.html#palace.Device.close">close() (palace.Device method)</a>
|
||||
|
||||
<ul>
|
||||
<li><a href="reference.html#palace.FileIO.close">(palace.FileIO attribute)</a>
|
||||
<li><a href="reference.html#palace.FileIO.close">(palace.FileIO method)</a>
|
||||
</li>
|
||||
</ul></li>
|
||||
<li><a href="reference.html#palace.Source.cone_angles">cone_angles (palace.Source attribute)</a>
|
||||
|
|
@ -161,23 +161,23 @@
|
|||
</li>
|
||||
<li><a href="reference.html#palace.ChorusEffect.depth">depth (palace.ChorusEffect attribute)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.BaseEffect.destroy">destroy (palace.BaseEffect attribute)</a>
|
||||
<li><a href="reference.html#palace.BaseEffect.destroy">destroy() (palace.BaseEffect method)</a>
|
||||
|
||||
<ul>
|
||||
<li><a href="reference.html#palace.Buffer.destroy">(palace.Buffer attribute)</a>
|
||||
<li><a href="reference.html#palace.Buffer.destroy">(palace.Buffer method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Context.destroy">(palace.Context attribute)</a>
|
||||
<li><a href="reference.html#palace.Context.destroy">(palace.Context method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Source.destroy">(palace.Source attribute)</a>
|
||||
<li><a href="reference.html#palace.Source.destroy">(palace.Source method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.SourceGroup.destroy">(palace.SourceGroup attribute)</a>
|
||||
<li><a href="reference.html#palace.SourceGroup.destroy">(palace.SourceGroup method)</a>
|
||||
</li>
|
||||
</ul></li>
|
||||
</ul></td>
|
||||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Device">Device (class in palace)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.MessageHandler.device_disconnected">device_disconnected (palace.MessageHandler attribute)</a>
|
||||
<li><a href="reference.html#palace.MessageHandler.device_disconnected">device_disconnected() (palace.MessageHandler method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.device_names">device_names (in module palace)</a>
|
||||
</li>
|
||||
|
|
@ -207,7 +207,7 @@
|
|||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Device.efx_version">efx_version() (palace.Device property)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Context.end_batch">end_batch (palace.Context attribute)</a>
|
||||
<li><a href="reference.html#palace.Context.end_batch">end_batch() (palace.Context method)</a>
|
||||
</li>
|
||||
</ul></td>
|
||||
</tr></table>
|
||||
|
|
@ -215,7 +215,7 @@
|
|||
<h2 id="F">F</h2>
|
||||
<table style="width: 100%" class="indextable genindextable"><tr>
|
||||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Source.fade_out_to_stop">fade_out_to_stop (palace.Source attribute)</a>
|
||||
<li><a href="reference.html#palace.Source.fade_out_to_stop">fade_out_to_stop() (palace.Source method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.ChorusEffect.feedback">feedback (palace.ChorusEffect attribute)</a>
|
||||
</li>
|
||||
|
|
@ -239,7 +239,7 @@
|
|||
<li><a href="reference.html#palace.Device.frequency">(palace.Device property)</a>
|
||||
</li>
|
||||
</ul></li>
|
||||
<li><a href="reference.html#palace.Buffer.from_decoder">from_decoder (palace.Buffer attribute)</a>
|
||||
<li><a href="reference.html#palace.Buffer.from_decoder">from_decoder() (palace.Buffer static method)</a>
|
||||
</li>
|
||||
</ul></td>
|
||||
</tr></table>
|
||||
|
|
@ -293,7 +293,7 @@
|
|||
<h2 id="I">I</h2>
|
||||
<table style="width: 100%" class="indextable genindextable"><tr>
|
||||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Context.is_supported">is_supported (palace.Context attribute)</a>
|
||||
<li><a href="reference.html#palace.Context.is_supported">is_supported() (palace.Context method)</a>
|
||||
</li>
|
||||
</ul></td>
|
||||
</tr></table>
|
||||
|
|
@ -401,11 +401,11 @@
|
|||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.SourceGroup.parent_group">parent_group (palace.SourceGroup attribute)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Source.pause">pause (palace.Source attribute)</a>
|
||||
<li><a href="reference.html#palace.Source.pause">pause() (palace.Source method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.SourceGroup.pause_all">pause_all (palace.SourceGroup attribute)</a>
|
||||
<li><a href="reference.html#palace.SourceGroup.pause_all">pause_all() (palace.SourceGroup method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Device.pause_dsp">pause_dsp (palace.Device attribute)</a>
|
||||
<li><a href="reference.html#palace.Device.pause_dsp">pause_dsp() (palace.Device method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Source.paused">paused() (palace.Source property)</a>
|
||||
</li>
|
||||
|
|
@ -419,10 +419,10 @@
|
|||
</ul></li>
|
||||
</ul></td>
|
||||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Buffer.play">play (palace.Buffer attribute)</a>
|
||||
<li><a href="reference.html#palace.Buffer.play">play() (palace.Buffer method)</a>
|
||||
|
||||
<ul>
|
||||
<li><a href="reference.html#palace.Decoder.play">(palace.Decoder attribute)</a>
|
||||
<li><a href="reference.html#palace.Decoder.play">(palace.Decoder method)</a>
|
||||
</li>
|
||||
</ul></li>
|
||||
<li><a href="reference.html#palace.Source.playing">playing() (palace.Source property)</a>
|
||||
|
|
@ -433,18 +433,27 @@
|
|||
</li>
|
||||
<li><a href="reference.html#palace.Source.priority">priority (palace.Source attribute)</a>
|
||||
</li>
|
||||
<li>
|
||||
Python Enhancement Proposals
|
||||
|
||||
<ul>
|
||||
<li><a href="contributing.html#index-1">PEP 257</a>
|
||||
</li>
|
||||
<li><a href="contributing.html#index-0">PEP 8</a>
|
||||
</li>
|
||||
</ul></li>
|
||||
</ul></td>
|
||||
</tr></table>
|
||||
|
||||
<h2 id="Q">Q</h2>
|
||||
<table style="width: 100%" class="indextable genindextable"><tr>
|
||||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Device.query_extension">query_extension (palace.Device attribute)</a>
|
||||
</li>
|
||||
</ul></td>
|
||||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.query_extension">query_extension() (in module palace)</a>
|
||||
|
||||
<ul>
|
||||
<li><a href="reference.html#palace.Device.query_extension">(palace.Device method)</a>
|
||||
</li>
|
||||
</ul></li>
|
||||
</ul></td>
|
||||
</tr></table>
|
||||
|
||||
|
|
@ -453,12 +462,12 @@
|
|||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Source.radius">radius (palace.Source attribute)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.BaseDecoder.read">read (palace.BaseDecoder attribute)</a>
|
||||
<li><a href="reference.html#palace.BaseDecoder.read">read() (palace.BaseDecoder method)</a>
|
||||
|
||||
<ul>
|
||||
<li><a href="reference.html#palace.Decoder.read">(palace.Decoder attribute)</a>
|
||||
<li><a href="reference.html#palace.Decoder.read">(palace.Decoder method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.FileIO.read">(palace.FileIO attribute)</a>
|
||||
<li><a href="reference.html#palace.FileIO.read">(palace.FileIO method)</a>
|
||||
</li>
|
||||
</ul></li>
|
||||
<li><a href="reference.html#palace.ReverbEffect.reflections_delay">reflections_delay (palace.ReverbEffect attribute)</a>
|
||||
|
|
@ -473,15 +482,15 @@
|
|||
</li>
|
||||
</ul></td>
|
||||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Device.reset">reset (palace.Device attribute)</a>
|
||||
<li><a href="reference.html#palace.Device.reset">reset() (palace.Device method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.MessageHandler.resource_not_found">resource_not_found (palace.MessageHandler attribute)</a>
|
||||
<li><a href="reference.html#palace.MessageHandler.resource_not_found">resource_not_found() (palace.MessageHandler method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Source.resume">resume (palace.Source attribute)</a>
|
||||
<li><a href="reference.html#palace.Source.resume">resume() (palace.Source method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.SourceGroup.resume_all">resume_all (palace.SourceGroup attribute)</a>
|
||||
<li><a href="reference.html#palace.SourceGroup.resume_all">resume_all() (palace.SourceGroup method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Device.resume_dsp">resume_dsp (palace.Device attribute)</a>
|
||||
<li><a href="reference.html#palace.Device.resume_dsp">resume_dsp() (palace.Device method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.reverb_preset_names">reverb_preset_names (in module palace)</a>
|
||||
</li>
|
||||
|
|
@ -513,12 +522,12 @@
|
|||
</ul></li>
|
||||
<li><a href="reference.html#palace.sample_types">sample_types (in module palace)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.BaseDecoder.seek">seek (palace.BaseDecoder attribute)</a>
|
||||
<li><a href="reference.html#palace.BaseDecoder.seek">seek() (palace.BaseDecoder method)</a>
|
||||
|
||||
<ul>
|
||||
<li><a href="reference.html#palace.Decoder.seek">(palace.Decoder attribute)</a>
|
||||
<li><a href="reference.html#palace.Decoder.seek">(palace.Decoder method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.FileIO.seek">(palace.FileIO attribute)</a>
|
||||
<li><a href="reference.html#palace.FileIO.seek">(palace.FileIO method)</a>
|
||||
</li>
|
||||
</ul></li>
|
||||
<li><a href="reference.html#palace.ReverbEffect.send_auto">send_auto() (palace.ReverbEffect property)</a>
|
||||
|
|
@ -535,11 +544,11 @@
|
|||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Buffer.source_count">source_count() (palace.Buffer property)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.MessageHandler.source_force_stopped">source_force_stopped (palace.MessageHandler attribute)</a>
|
||||
<li><a href="reference.html#palace.MessageHandler.source_force_stopped">source_force_stopped() (palace.MessageHandler method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.BaseEffect.source_sends">source_sends() (palace.BaseEffect property)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.MessageHandler.source_stopped">source_stopped (palace.MessageHandler attribute)</a>
|
||||
<li><a href="reference.html#palace.MessageHandler.source_stopped">source_stopped() (palace.MessageHandler method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.SourceGroup">SourceGroup (class in palace)</a>
|
||||
</li>
|
||||
|
|
@ -553,15 +562,15 @@
|
|||
</li>
|
||||
<li><a href="reference.html#palace.Context.speed_of_sound">speed_of_sound() (palace.Context property)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Context.start_batch">start_batch (palace.Context attribute)</a>
|
||||
<li><a href="reference.html#palace.Context.start_batch">start_batch() (palace.Context method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Source.stereo_angles">stereo_angles (palace.Source attribute)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.STEREO_SOURCES">STEREO_SOURCES (in module palace)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.Source.stop">stop (palace.Source attribute)</a>
|
||||
<li><a href="reference.html#palace.Source.stop">stop() (palace.Source method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.SourceGroup.stop_all">stop_all (palace.SourceGroup attribute)</a>
|
||||
<li><a href="reference.html#palace.SourceGroup.stop_all">stop_all() (palace.SourceGroup method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.SourceGroup.sub_groups">sub_groups() (palace.SourceGroup property)</a>
|
||||
</li>
|
||||
|
|
@ -579,7 +588,7 @@
|
|||
<h2 id="U">U</h2>
|
||||
<table style="width: 100%" class="indextable genindextable"><tr>
|
||||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#palace.Context.update">update (palace.Context attribute)</a>
|
||||
<li><a href="reference.html#palace.Context.update">update() (palace.Context method)</a>
|
||||
</li>
|
||||
<li><a href="reference.html#palace.use_context">use_context() (in module palace)</a>
|
||||
</li>
|
||||
|
|
@ -620,31 +629,39 @@
|
|||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h1 class="logo"><a href="index.html">palace</a></h1>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<h3>Navigation</h3>
|
||||
<p class="caption"><span class="caption-text">Contents:</span></p>
|
||||
<h3><a href="index.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="design.html">Design Principles</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Getting Involved</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="copying.html">Copying</a></li>
|
||||
</ul>
|
||||
|
||||
<div class="relations">
|
||||
<h3>Related Topics</h3>
|
||||
<h3>Quick Navigation</h3>
|
||||
<ul>
|
||||
<li><a href="index.html">Documentation overview</a><ul>
|
||||
</ul></li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://pypi.org/project/palace/">
|
||||
Python Package Index
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://travis-ci.com/github/McSinyx/palace">
|
||||
Travis CI Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://ci.appveyor.com/project/McSinyx/palace">
|
||||
AppVeyor Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://github.com/McSinyx/palace">
|
||||
GitHub Repository
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div id="searchbox" style="display: none" role="search">
|
||||
<h3 id="searchlabel">Quick search</h3>
|
||||
<div class="searchformwrapper">
|
||||
|
|
@ -655,14 +672,6 @@
|
|||
</div>
|
||||
</div>
|
||||
<script>$('#searchbox').show(0);</script>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
|
|
@ -671,7 +680,7 @@
|
|||
©2019, 2020 Nguyễn Gia Phong et al.
|
||||
|
||||
|
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.1</a>
|
||||
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
||||
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Welcome to our palace! — palace 0.1.5 documentation</title>
|
||||
<title>Welcome to our palace! — palace 0.2.0 documentation</title>
|
||||
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||||
|
|
@ -33,8 +33,13 @@
|
|||
|
||||
<div class="section" id="welcome-to-our-palace">
|
||||
<h1>Welcome to our palace!<a class="headerlink" href="#welcome-to-our-palace" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Pythonic Audio Library and Codecs Environment provides common higher-level API
|
||||
for audio rendering using OpenAL. It wraps around the C++ interface <a class="reference external" href="https://github.com/kcat/alure">alure</a>
|
||||
for 3D positional rendering, environmental effects and out-of-the-box
|
||||
codec support, while using Cython to provide a modern interface with
|
||||
type hinting, data descriptors, context managers and <code class="docutils literal notranslate"><span class="pre">snake_case</span></code>
|
||||
for a safe, convenient and pleasurable experience.</p>
|
||||
<div class="toctree-wrapper compound">
|
||||
<p class="caption"><span class="caption-text">Contents:</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="installation.html#prerequisites">Prerequisites</a></li>
|
||||
|
|
@ -58,6 +63,14 @@
|
|||
<li class="toctree-l2"><a class="reference internal" href="design.html#the-double-reference">The Double Reference</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Getting Involved</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="contributing.html#reporting-a-bug">Reporting a Bug</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="contributing.html#requesting-a-feature">Requesting a Feature</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="contributing.html#submitting-a-patch">Submitting a Patch</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="contributing.html#making-a-release">Making a Release</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="contributing.html#style-guidelines">Style Guidelines</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="copying.html">Copying</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="copying.html#license">License</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="copying.html#credits">Credits</a></li>
|
||||
|
|
@ -82,32 +95,39 @@
|
|||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h1 class="logo"><a href="#">palace</a></h1>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<h3>Navigation</h3>
|
||||
<p class="caption"><span class="caption-text">Contents:</span></p>
|
||||
<h3><a href="#">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="design.html">Design Principles</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Getting Involved</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="copying.html">Copying</a></li>
|
||||
</ul>
|
||||
|
||||
<div class="relations">
|
||||
<h3>Related Topics</h3>
|
||||
<h3>Quick Navigation</h3>
|
||||
<ul>
|
||||
<li><a href="#">Documentation overview</a><ul>
|
||||
<li>Next: <a href="installation.html" title="next chapter">Installation</a></li>
|
||||
</ul></li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://pypi.org/project/palace/">
|
||||
Python Package Index
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://travis-ci.com/github/McSinyx/palace">
|
||||
Travis CI Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://ci.appveyor.com/project/McSinyx/palace">
|
||||
AppVeyor Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://github.com/McSinyx/palace">
|
||||
GitHub Repository
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div id="searchbox" style="display: none" role="search">
|
||||
<h3 id="searchlabel">Quick search</h3>
|
||||
<div class="searchformwrapper">
|
||||
|
|
@ -118,14 +138,6 @@
|
|||
</div>
|
||||
</div>
|
||||
<script>$('#searchbox').show(0);</script>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
|
|
@ -134,7 +146,7 @@
|
|||
©2019, 2020 Nguyễn Gia Phong et al.
|
||||
|
||||
|
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.1</a>
|
||||
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
||||
|
||||
|
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Installation — palace 0.1.5 documentation</title>
|
||||
<title>Installation — palace 0.2.0 documentation</title>
|
||||
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||||
|
|
@ -36,7 +36,8 @@
|
|||
<h1>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="section" id="prerequisites">
|
||||
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Palace requires Python 3.6 for runtime and <a class="reference external" href="https://pip.pypa.io/en/latest/">pip</a> for installation.</p>
|
||||
<p>Palace requires <a class="reference external" href="https://www.python.org/">CPython</a> version 3.6 or above for runtime
|
||||
and <a class="reference external" href="https://pip.pypa.io/en/latest/">pip</a> for installation.</p>
|
||||
</div>
|
||||
<div class="section" id="via-pypi">
|
||||
<h2>Via PyPI<a class="headerlink" href="#via-pypi" title="Permalink to this headline">¶</a></h2>
|
||||
|
|
@ -45,17 +46,17 @@
|
|||
</pre></div>
|
||||
</div>
|
||||
<p>Wheel distributions are built exclusively for amd64. Currently, only GNU/Linux
|
||||
is properly supported. If you want to help packaging for Windows and macOS,
|
||||
see <a class="reference external" href="https://github.com/McSinyx/palace/issues/1">GH-1</a> and <a class="reference external" href="https://github.com/McSinyx/palace/issues/63">GH-63</a> respectively on our issues tracker on GitHub.</p>
|
||||
and macOS are properly supported. If you want to help packaging for Windows,
|
||||
please see <a class="reference external" href="https://github.com/McSinyx/palace/issues/1">GH-1</a> on our issues tracker on GitHub.</p>
|
||||
</div>
|
||||
<div class="section" id="from-source">
|
||||
<h2>From source<a class="headerlink" href="#from-source" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Aside from the build dependencies listed in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>,
|
||||
one will additionally need compatible Python headers, <a class="reference external" href="https://github.com/kcat/alure">alure</a>,
|
||||
a C++14 compiler, CMake 2.6+ (and probably <code class="docutils literal notranslate"><span class="pre">git</span></code> for fetching the source).
|
||||
a C++14 compiler, <a class="reference external" href="https://cmake.org/">CMake</a> 2.6+ (and probably <a class="reference external" href="https://git-scm.com/">git</a> for fetching the source).
|
||||
Palace can then be compiled and installed by running:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/McSinyx/palace.git
|
||||
pip install palace/
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">McSinyx</span><span class="o">/</span><span class="n">palace</span><span class="o">.</span><span class="n">git</span>
|
||||
<span class="n">pip</span> <span class="n">install</span> <span class="n">palace</span><span class="o">/</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -68,17 +69,7 @@ pip install palace/
|
|||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h1 class="logo"><a href="index.html">palace</a></h1>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<h3>Navigation</h3>
|
||||
<p class="caption"><span class="caption-text">Contents:</span></p>
|
||||
<h3><a href="index.html">Table of Contents</a></h3>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Installation</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
|
||||
|
|
@ -88,18 +79,34 @@ pip install palace/
|
|||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="design.html">Design Principles</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Getting Involved</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="copying.html">Copying</a></li>
|
||||
</ul>
|
||||
|
||||
<div class="relations">
|
||||
<h3>Related Topics</h3>
|
||||
<h3>Quick Navigation</h3>
|
||||
<ul>
|
||||
<li><a href="index.html">Documentation overview</a><ul>
|
||||
<li>Previous: <a href="index.html" title="previous chapter">Welcome to our palace!</a></li>
|
||||
<li>Next: <a href="reference.html" title="next chapter">Reference</a></li>
|
||||
</ul></li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://pypi.org/project/palace/">
|
||||
Python Package Index
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://travis-ci.com/github/McSinyx/palace">
|
||||
Travis CI Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://ci.appveyor.com/project/McSinyx/palace">
|
||||
AppVeyor Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://github.com/McSinyx/palace">
|
||||
GitHub Repository
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div id="searchbox" style="display: none" role="search">
|
||||
<h3 id="searchlabel">Quick search</h3>
|
||||
<div class="searchformwrapper">
|
||||
|
|
@ -110,14 +117,6 @@ pip install palace/
|
|||
</div>
|
||||
</div>
|
||||
<script>$('#searchbox').show(0);</script>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
|
|
@ -126,7 +125,7 @@ pip install palace/
|
|||
©2019, 2020 Nguyễn Gia Phong et al.
|
||||
|
||||
|
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.1</a>
|
||||
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
||||
|
||||
|
|
||||
|
|
|
|||
BIN
html/objects.inv
BIN
html/objects.inv
Binary file not shown.
File diff suppressed because it is too large
Load Diff
|
|
@ -1,10 +1,10 @@
|
|||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Search — palace 0.1.5 documentation</title>
|
||||
<title>Search — palace 0.2.0 documentation</title>
|
||||
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
|
||||
|
|
@ -44,10 +44,8 @@
|
|||
</p>
|
||||
</div>
|
||||
<p>
|
||||
From here you can search these documents. Enter your search
|
||||
words into the box below and click "search". Note that the search
|
||||
function will automatically search for all of the words. Pages
|
||||
containing fewer words won't appear in the result list.
|
||||
Searching for multiple words only shows matches that contain
|
||||
all words.
|
||||
</p>
|
||||
<form action="" method="get">
|
||||
<input type="text" name="q" aria-labelledby="search-documentation" value="" />
|
||||
|
|
@ -65,39 +63,39 @@
|
|||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h1 class="logo"><a href="index.html">palace</a></h1>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<h3>Navigation</h3>
|
||||
<p class="caption"><span class="caption-text">Contents:</span></p>
|
||||
<h3><a href="index.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="design.html">Design Principles</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Getting Involved</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="copying.html">Copying</a></li>
|
||||
</ul>
|
||||
|
||||
<div class="relations">
|
||||
<h3>Related Topics</h3>
|
||||
<h3>Quick Navigation</h3>
|
||||
<ul>
|
||||
<li><a href="index.html">Documentation overview</a><ul>
|
||||
</ul></li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://pypi.org/project/palace/">
|
||||
Python Package Index
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://travis-ci.com/github/McSinyx/palace">
|
||||
Travis CI Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://ci.appveyor.com/project/McSinyx/palace">
|
||||
AppVeyor Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://github.com/McSinyx/palace">
|
||||
GitHub Repository
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
|
|
@ -106,7 +104,7 @@
|
|||
©2019, 2020 Nguyễn Gia Phong et al.
|
||||
|
||||
|
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
|
||||
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.1</a>
|
||||
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
||||
|
||||
</div>
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1,25 @@
|
|||
<h3>Quick Navigation</h3>
|
||||
<ul>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://pypi.org/project/palace/">
|
||||
Python Package Index
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://travis-ci.com/github/McSinyx/palace">
|
||||
Travis CI Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external"
|
||||
href="https://ci.appveyor.com/project/McSinyx/palace">
|
||||
AppVeyor Build
|
||||
</a>
|
||||
</li>
|
||||
<li class="toctree-l1">
|
||||
<a class="reference external" href="https://github.com/McSinyx/palace">
|
||||
GitHub Repository
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
|
|
@ -22,7 +22,7 @@ copyright = '2019, 2020 Nguyễn Gia Phong et al'
|
|||
author = 'Nguyễn Gia Phong et al.'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = '0.1.5'
|
||||
release = '0.2.0'
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
|
@ -51,6 +51,9 @@ exclude_patterns = []
|
|||
#
|
||||
html_theme = 'alabaster'
|
||||
|
||||
html_sidebars = {
|
||||
'**': ['globaltoc.html', 'quicknav.html', 'searchbox.html']}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
|
|
|
|||
|
|
@ -0,0 +1,203 @@
|
|||
Getting Involved
|
||||
================
|
||||
|
||||
.. note:: The development of palace is carried out on GitHub_.
|
||||
Since GitHub is not free software, we fully understand
|
||||
if one does not want to register an account just to participate
|
||||
in our development. Therefore, we also welcome patches
|
||||
and bug reports sent via email.
|
||||
|
||||
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,
|
||||
feature requests and patches than a giant one. There is no limit for
|
||||
the number of contributions one may or should make. While it may seem
|
||||
appealing to be able to dump all thoughts and feelings into one ticket,
|
||||
it would be more difficult for us to keep track of the progress.
|
||||
|
||||
Reporting a Bug
|
||||
---------------
|
||||
|
||||
Before filing a bug report, please make sure that the bug has not been
|
||||
already reported by searching our GitHub Issues_ tracker.
|
||||
|
||||
To facilitate the debugging process, a bug report should at least contain
|
||||
the following information:
|
||||
|
||||
#. The platform, the CPython version and the compiler used to build it.
|
||||
These can be obtained from :py:func:`platform.platform`,
|
||||
:py:func:`platform.python_version` and :py:func:`platform.python_compiler`,
|
||||
respectively.
|
||||
#. The version of palace and how you installed it.
|
||||
The earlier is usually provided by ``pip show palace``.
|
||||
#. Detailed instructions on how to reproduce the bug,
|
||||
for example a short Python script would be appreciated.
|
||||
|
||||
Requesting a Feature
|
||||
--------------------
|
||||
|
||||
Prior to filing a feature request, please make sure that the feature
|
||||
has not been already reported by searching our GitHub Issues_ tracker.
|
||||
|
||||
Please only ask for features that you (or an incapacitated friend
|
||||
you can personally talk to) require. Do not request features because
|
||||
they seem like a good idea. If they are really useful, they will be
|
||||
requested by someone who requires them.
|
||||
|
||||
Submitting a Patch
|
||||
------------------
|
||||
|
||||
We accept all kinds of patches, from documentation and CI/CD setup
|
||||
to bug fixes, feature implementations and tests. Except for documentation
|
||||
located in the ``gh-pages`` branch, others should be filed against
|
||||
the development branch ``master``. These are hosted on GitHub and
|
||||
one may create a local repository by running::
|
||||
|
||||
git clone https://github.com/McSinyx/palace
|
||||
|
||||
While the patch can be submitted via email, it is preferable to file
|
||||
a pull request on GitHub to allow more people to review it, since we do not
|
||||
have any mail list. Either way, contributors must have legal permission
|
||||
to distribute the code and it must be available under `LGPLv3+`_. Furthermore,
|
||||
each contributor retains the copyrights of their patch, to ensure that
|
||||
the licence can never be revoked even if others wants to. It is advisable
|
||||
that the author list per legal name under the copyright header
|
||||
of each source file they modify, like so::
|
||||
|
||||
Copyright (C) 2038 Foo Bar
|
||||
|
||||
Using GitHub
|
||||
^^^^^^^^^^^^
|
||||
|
||||
#. Create a fork_ of our repository on GitHub.
|
||||
#. Checkout the source code and (optionally) add the ``upstream`` remote::
|
||||
|
||||
git clone https://github.com/YOUR_GITHUB_USERNAME/palace
|
||||
cd palace
|
||||
git remote add upstream https://github.com/McSinyx/palace
|
||||
|
||||
#. Start working on your patch and make sure your code complies with
|
||||
the `Style Guidelines`_ and passes the test suit run by tox_.
|
||||
#. Add relevant tests to the patch and work on it until they all pass.
|
||||
In case one is only modifying tests, perse may install palace using
|
||||
``CYTHON_TRACE=1 pip install .`` then run pytest_ directly to avoid
|
||||
having to build the extension module multiple times.
|
||||
#. Update the copyright notices of the files you modified.
|
||||
Palace is collectively licensed under `LGPLv3+`_,
|
||||
and to protect the freedom of the users,
|
||||
copyright holders need to be properly documented.
|
||||
#. Add_, commit_ with `a great message`_ then push_ the result.
|
||||
#. Finally, `create a pull request`_. We will then review and merge it.
|
||||
|
||||
It is recommended to create a new branch in your fork
|
||||
(``git checkout -c what-you-are-working-on``) instead of working directly
|
||||
on ``master``. This way one can still sync per fork with our ``master`` branch
|
||||
and ``git pull --rebase upstream master`` to avoid integration issues.
|
||||
|
||||
Via Email
|
||||
^^^^^^^^^
|
||||
|
||||
#. Checkout the source code::
|
||||
|
||||
git clone https://github.com/McSinyx/palace
|
||||
cd palace
|
||||
|
||||
#. Work on your patch with tests and copyright notice included
|
||||
as described above.
|
||||
#. `git-format-patch`_ and send it to one of the maintainers
|
||||
(our emails addresses are available under ``git log``).
|
||||
We will then review and merge it.
|
||||
|
||||
In any case, thank you very much for your contributions!
|
||||
|
||||
Making a Release
|
||||
----------------
|
||||
|
||||
While this is meant for developers doing a palace release, contributors wishing
|
||||
to improve the CI/CD may find it helpful.
|
||||
|
||||
#. Under the local repository, checkout the ``master`` branch
|
||||
and sync with the one on GitHub using ``git pull``.
|
||||
#. Bump the version in ``setup.cfg`` and push to GitHub.
|
||||
#. Create a source distribution by running ``setup.py sdist``.
|
||||
The distribution generated by this command is now referred to as ``sdist``.
|
||||
#. Using twine_, upload the ``sdist`` to PyPI via ``twine upload $sdist``.
|
||||
#. On GitHub, tag a new release with the ``sdist`` attached.
|
||||
In the release note, make sure to include all user-facing changes
|
||||
since the previous release. This will trigger the CD services
|
||||
to build the wheels and publish them to PyPI.
|
||||
#. Wait for the wheel for your platform to arrive to PyPI and install it.
|
||||
Play around with it for a little to make sure that everything is OK.
|
||||
#. Under the local repository, checkout the ``gh-pages`` branch.
|
||||
Often, is it necessary to update the credits under the :doc:`copying`
|
||||
section and review if the :doc:`reference` section needs any change
|
||||
before running ``make html`` to rebuild to documentation.
|
||||
#. View the documentation locally then push it to GitHub.
|
||||
|
||||
Style Guidelines
|
||||
----------------
|
||||
|
||||
Python and Cython
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Generally, palace follows :pep:`8` and :pep:`257`,
|
||||
with the following preferences and exceptions:
|
||||
|
||||
* Hanging indentation is *always* preferred,
|
||||
where continuation lines are indented by 4 spaces.
|
||||
* Comments and one-line docstrings are limited to column 79
|
||||
instead of 72 like for multi-line docstrings.
|
||||
* Cython extern declarations need not follow the 79-character limit.
|
||||
* Break long lines before a binary operator.
|
||||
* Use form feeds sparingly to break long modules
|
||||
into pages of relating functions and classes.
|
||||
* Prefer single-quoted strings over double-quoted strings,
|
||||
unless the string contains single quote characters.
|
||||
* Avoid trailing commas at all costs.
|
||||
* Line breaks within comments and docstrings should not cut a phrase in half.
|
||||
* Everything deserves a docstring. Palace follows numpydoc_ which support
|
||||
documenting attributes as well as constants and module-level variables.
|
||||
In additional to docstrings, type annotations should be employed
|
||||
for all public names.
|
||||
* 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
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
In order for reStructuredText to be rendered correctly, the body of
|
||||
constructs beginning with a marker (lists, hyperlink targets, comments, etc.)
|
||||
must be aligned relative to the marker. For this reason, it is convenient
|
||||
to set your editor indentation level to 3 spaces, since most constructs
|
||||
starts with two dots and a space. However, be aware of that bullet items
|
||||
require 2-space alignment and other exceptions.
|
||||
|
||||
Limit all lines to a maximum of 79 characters. Similar to comments
|
||||
and docstrings, phrases should not be broken in the middle.
|
||||
The source code of this guide itself is a good example on how line breaks
|
||||
should be handled. Additionally, two spaces should also be used
|
||||
after a sentence-ending period in multi-sentence paragraph,
|
||||
except after the final sentence.
|
||||
|
||||
.. _GitHub: https://github.com/McSinyx/palace
|
||||
.. _the mo the merier:
|
||||
https://www.phrases.org.uk/meanings/the-more-the-merrier.html
|
||||
.. _Issues: https://github.com/McSinyx/palace/issues
|
||||
.. _LGPLv3+: https://www.gnu.org/licenses/lgpl-3.0.en.html
|
||||
.. _fork: https://github.com/McSinyx/palace/fork
|
||||
.. _tox: https://tox.readthedocs.io/en/latest/
|
||||
.. _pytest: https://docs.pytest.org/en/latest/
|
||||
.. _Add: https://git-scm.com/docs/git-add
|
||||
.. _commit: https://git-scm.com/docs/git-commit
|
||||
.. _a great message: https://chris.beams.io/posts/git-commit/#seven-rules
|
||||
.. _push: https://git-scm.com/docs/git-push
|
||||
.. _create a pull request:
|
||||
https://help.github.com/articles/creating-a-pull-request
|
||||
.. _git-format-patch: https://git-scm.com/docs/git-format-patch
|
||||
.. _twine: https://twine.readthedocs.io/en/latest/
|
||||
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
|
||||
.. _Octave: https://wiki.octave.org/C%2B%2B_style_guide
|
||||
|
|
@ -1,6 +1,12 @@
|
|||
Copying
|
||||
=======
|
||||
|
||||
This listing is our best-faith, hard-work effort at accurate attribution,
|
||||
sources, and licenses for everything in palace. If you discover
|
||||
an asset/contribution that is incorrectly attributed or licensed,
|
||||
please contact us immediately. We are happy to do everything we can
|
||||
to fix or remove the issue.
|
||||
|
||||
License
|
||||
-------
|
||||
Palace is free software: you can redistribute it and/or modify it
|
||||
|
|
@ -8,24 +14,18 @@ under the terms of the `GNU Lesser General Public License`_
|
|||
as published by the Free Software Foundation, either version 3
|
||||
of the License, or (at your option) any later version.
|
||||
|
||||
.. _GNU Lesser General Public License:
|
||||
https://www.gnu.org/licenses/lgpl-3.0.en.html
|
||||
|
||||
Credits
|
||||
-------
|
||||
|
||||
To ensure that palace can run without any dependencies outside of the `pip`_
|
||||
To ensure that palace can run without any dependencies outside of the pip_
|
||||
toolchain, the wheels are bundled with dynamically linked libraries from
|
||||
the build machine, which is similar to static linking:
|
||||
|
||||
============== ============
|
||||
Library License
|
||||
============== ============
|
||||
`Alure`_ ZLib
|
||||
Alure_ ZLib
|
||||
`OpenAL Soft`_ GNU LGPLv2+
|
||||
`Vorbis`_ 3-clause BSD
|
||||
`Opus`_ 3-clause BSD
|
||||
`libsndfile`_ GNU LGPL2.1+
|
||||
Vorbis_ 3-clause BSD
|
||||
Opus_ 3-clause BSD
|
||||
libsndfile_ GNU LGPL2.1+
|
||||
============== ============
|
||||
|
||||
In addition, the following sounds are used for testing:
|
||||
|
|
@ -40,6 +40,22 @@ Sound (located in ``tests/data``) License
|
|||
`99642__jobro__deconvoluted-20hz-to-20khz.wav`_ CC BY 3.0
|
||||
=============================================== =========
|
||||
|
||||
Credits
|
||||
-------
|
||||
|
||||
Palace would never have seen the light of day without the help from
|
||||
the developers of Alure_ and Cython_ who promptly gave detail answers
|
||||
and made quick fixes to all of our problems.
|
||||
|
||||
The wheels are build using cibuildwheel_, which made building extension modules
|
||||
much less of a painful experience. `Travis CI`_ and AppVeyor_ kindly provides
|
||||
their services free of charge for automated CI/CD.
|
||||
|
||||
This documentation is generated using Sphinx_, whose maintainer responses
|
||||
extreamly quickly to obsolete Cython-related issues.
|
||||
|
||||
.. _GNU Lesser General Public License:
|
||||
https://www.gnu.org/licenses/lgpl-3.0.en.html
|
||||
.. _pip: https://pip.pypa.io/en/latest/
|
||||
.. _Alure: https://github.com/kcat/alure
|
||||
.. _OpenAL Soft: https://kcat.strangesoft.net/openal.html
|
||||
|
|
@ -51,3 +67,8 @@ Sound (located in ``tests/data``) License
|
|||
.. _261590__kwahmah-02__little-glitch.flac: https://freesound.org/s/261590/
|
||||
.. _353684__tec-studio__drip2.mp3: https://freesound.org/s/353684/
|
||||
.. _99642__jobro__deconvoluted-20hz-to-20khz.wav: https://freesound.org/s/99642/
|
||||
.. _Cython: https://cython.org/
|
||||
.. _cibuildwheel: https://cibuildwheel.readthedocs.io/en/stable/
|
||||
.. _Sphinx: https://www.sphinx-doc.org/en/master/
|
||||
.. _Travis CI: https://travis-ci.com/
|
||||
.. _AppVeyor: https://www.appveyor.com/
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ 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.
|
||||
|
||||
.. _alure: https://github.com/kcat/alure
|
||||
|
||||
.. _impl-idiom:
|
||||
|
||||
The Impl Idiom
|
||||
|
|
@ -48,8 +46,6 @@ The Cython extension type can then be declared as follows
|
|||
def meth(self, crack: int) -> float:
|
||||
return self.impl.meth(crack)
|
||||
|
||||
.. _`the pimpl idiom`: https://wiki.c2.com/?PimplIdiom
|
||||
|
||||
The Modern Python
|
||||
-----------------
|
||||
|
||||
|
|
@ -81,8 +77,6 @@ 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.
|
||||
|
||||
.. _property: https://docs.python.org/3/library/functions.html#property
|
||||
|
||||
Context Managers
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -183,3 +177,7 @@ In practice, :py:class:`palace.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
|
||||
|
|
|
|||
|
|
@ -1,13 +1,20 @@
|
|||
Welcome to our palace!
|
||||
======================
|
||||
|
||||
Pythonic Audio Library and Codecs Environment provides common higher-level API
|
||||
for audio rendering using OpenAL. It wraps around the C++ interface alure_
|
||||
for 3D positional rendering, environmental effects and out-of-the-box
|
||||
codec support, while using Cython to provide a modern interface with
|
||||
type hinting, data descriptors, context managers and ``snake_case``
|
||||
for a safe, convenient and pleasurable experience.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
installation
|
||||
reference
|
||||
design
|
||||
contributing
|
||||
copying
|
||||
|
||||
|
||||
|
|
@ -17,3 +24,5 @@ Indices and tables
|
|||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
.. _alure: https://github.com/kcat/alure
|
||||
|
|
|
|||
|
|
@ -4,9 +4,8 @@ Installation
|
|||
Prerequisites
|
||||
-------------
|
||||
|
||||
Palace requires Python 3.6 for runtime and `pip`_ for installation.
|
||||
|
||||
.. _pip: https://pip.pypa.io/en/latest/
|
||||
Palace requires CPython_ version 3.6 or above for runtime
|
||||
and pip_ for installation.
|
||||
|
||||
Via PyPI
|
||||
--------
|
||||
|
|
@ -16,23 +15,23 @@ Palace can be installed from PyPI::
|
|||
pip install palace
|
||||
|
||||
Wheel distributions are built exclusively for amd64. Currently, only GNU/Linux
|
||||
is properly supported. If you want to help packaging for Windows and macOS,
|
||||
see `GH-1`_ and `GH-63`_ respectively on our issues tracker on GitHub.
|
||||
|
||||
.. _GH-1: https://github.com/McSinyx/palace/issues/1
|
||||
.. _GH-63: https://github.com/McSinyx/palace/issues/63
|
||||
and macOS are properly supported. If you want to help packaging for Windows,
|
||||
please see `GH-1`_ on our issues tracker on GitHub.
|
||||
|
||||
From source
|
||||
-----------
|
||||
|
||||
Aside from the build dependencies listed in ``pyproject.toml``,
|
||||
one will additionally need compatible Python headers, `alure`_,
|
||||
a C++14 compiler, CMake 2.6+ (and probably ``git`` for fetching the source).
|
||||
Palace can then be compiled and installed by running:
|
||||
|
||||
.. code-block:: sh
|
||||
one will additionally need compatible Python headers, alure_,
|
||||
a C++14 compiler, CMake_ 2.6+ (and probably git_ for fetching the source).
|
||||
Palace can then be compiled and installed by running::
|
||||
|
||||
git clone https://github.com/McSinyx/palace.git
|
||||
pip install palace/
|
||||
|
||||
.. _CPython: https://www.python.org/
|
||||
.. _pip: https://pip.pypa.io/en/latest/
|
||||
.. _GH-1: https://github.com/McSinyx/palace/issues/1
|
||||
.. _alure: https://github.com/kcat/alure
|
||||
.. _CMake: https://cmake.org/
|
||||
.. _git: https://git-scm.com/
|
||||
|
|
|
|||
|
|
@ -112,6 +112,10 @@ Sources & Source Groups
|
|||
Environmental Effects
|
||||
---------------------
|
||||
|
||||
For the sake of brevity, we only document the constraints of each effect's
|
||||
properties. Further details can be found at OpenAL's `Effect Extension Guide`_
|
||||
which specifies the purpose and usage of each value.
|
||||
|
||||
.. data:: reverb_preset_names
|
||||
:type: Tuple[str, ...]
|
||||
|
||||
|
|
@ -122,7 +126,6 @@ Environmental Effects
|
|||
|
||||
.. autoclass:: ReverbEffect
|
||||
:members:
|
||||
:undoc-members:
|
||||
|
||||
.. autoclass:: ChorusEffect
|
||||
:members:
|
||||
|
|
@ -170,3 +173,6 @@ File I/O Interface
|
|||
|
||||
.. autoclass:: FileIO
|
||||
:members:
|
||||
|
||||
.. _Effect Extension Guide:
|
||||
https://kcat.strangesoft.net/misc-downloads/Effects%20Extension%20Guide.pdf
|
||||
|
|
|
|||
Loading…
Reference in New Issue