~cnx/palace

0bf8785db1890877522d0e143af44a1bae281c35 — Nguyễn Gia Phong 11 months ago 33cca1b
Update docs to reflect migration to SourceHut

Documentation is now hosted by GitLab Pages.
A .builds/docs.yaml => .builds/docs.yaml +18 -0
@@ 0,0 1,18 @@
image: python:slim
before_script:
  - apt-get update
  - apt-get install -y git cmake build-essential libopenal-dev
  - git clone https://github.com/kcat/alure
  - cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr -S alure -B alure/build
  - cmake --build alure/build --parallel `nproc` --target install
  - rm -fr alure
pages:
  stage: deploy
  script:
    - python -m pip install Sphinx sphinx_rtd_theme .
    - sphinx-build -bhtml docs/source public
  artifacts:
    paths:
      - public
  only:
    - main

M README.md => README.md +9 -9
@@ 27,9 27,9 @@ Palace can be install from the [Python Package Index][PyPI] via simply

    pip install palace

Wheel distributions are built exclusively for amd64.  Currently, only GNU/Linux
and macOS are properly supported.  If you want to help packaging for Windows,
please see [GH-1] on our issues tracker on GitHub.
Wheel distributions are built exclusively for GNU/Linux on amd64.
If you want to help packaging for other platforms, please reach out
on [our mailing list][list].

### From source
Aside from the build dependencies listed in `pyproject.toml`, one will


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

    pip install git+https://github.com/McSinyx/palace
    pip install git+https://git.sr.ht/~cnx/palace

## Usage
One may start with the `examples` for sample usage of palace.


@@ 64,10 64,10 @@ can be found in our documentation.
[Cython]: https://cython.org/
[pip]: https://pip.pypa.io/en/latest/
[PyPI]: https://pypi.org/project/palace/
[GH-1]: https://github.com/McSinyx/palace/issues/1
[CMake]: https://cmake.org/
[API]: https://mcsinyx.github.io/palace/reference.html
[contrib]: https://mcsinyx.github.io/palace/contributing.html
[design]: https://mcsinyx.github.io/palace/design.html
[list]: https://lists.sr.ht/~cnx/palace
[API]: https://mcsinyx.gitlab.io/palace/reference.html
[contrib]: https://mcsinyx.gitlab.io/palace/contributing.html
[design]: https://mcsinyx.gitlab.io/palace/design.html
[LGPLv3+]: https://www.gnu.org/licenses/lgpl-3.0.en.html
[copying]: https://mcsinyx.github.io/palace/copying.html
[copying]: https://mcsinyx.gitlab.io/palace/copying.html

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

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


@@ 19,7 19,7 @@ napoleon_google_docstring = False
default_role = 'py:obj'

# Add any paths that contain templates here, relative to this directory.
templates_path = ['templates']
templates_path = []

# List of patterns, relative to source directory, that match
# files and directories to ignore when looking for source files.

M docs/source/contributing.rst => docs/source/contributing.rst +34 -68
@@ 1,12 1,6 @@
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,


@@ 19,7 13,7 @@ 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.
already reported by searching our `bug tracker`_.

To facilitate the debugging process, a bug report should at least contain
the following information:


@@ 37,7 31,7 @@ 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.
has not been already requested by searching our `mailing list`_.

Please only ask for features that you (or an incapacitated friend
you can personally talk to) require.  Do not request features because


@@ 48,31 42,23 @@ Submitting a Patch
------------------

We accept all kinds of patches, from documentation and CI/CD setup
to bug fixes, feature implementations and tests.  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 against the ``master`` branch 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
to bug fixes, feature implementations and tests.  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::
of their patch, to ensure that the licence can never be revoked
even if others wants to.  It is advisable that the author lists
per legal name under the copyright header of each source file
perse modify, like so::

   Copyright (C) 2038  Foo Bar

Using GitHub
^^^^^^^^^^^^
The contribution process consists of the following steps:

#. Create a fork_ of our repository on GitHub.
#. Checkout the source code and (optionally) add the ``upstream`` remote::
#. Clone the upstream repository and configure the local one::

      git clone https://github.com/YOUR_GITHUB_USERNAME/palace
      git clone https://git.sr.ht/~cnx/palace
      cd palace
      git remote add upstream https://github.com/McSinyx/palace
      git config sendemail.to "~cnx/palace@lists.sr.ht"

#. Start working on your patch and make sure your code complies with
   the `Style Guidelines`_ and passes the test suit run by tox_.


@@ 81,30 67,8 @@ Using GitHub
   ``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.
#. Add_ and commit_ with `a great message`_.
#. `Send the patch and response to feedback. <git-send-email>`_

In any case, thank you very much for your contributions!



@@ 114,18 78,18 @@ 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.
#. Under the local repository, checkout the ``main`` branch
   and sync with the one on SourceHut using ``git pull``.
#. Bump the version in ``setup.cfg`` and ``docs/source/conf.py``,
   tag_ the commit and push it to SourceHut.  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_.
#. 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.
#. Announce to the `mailing list`_.  With fear and trembling.

Style Guidelines
----------------


@@ 162,6 126,9 @@ C++ codes should follow GNU style, which is best documented at Octave_.
reStructuredText
^^^^^^^^^^^^^^^^

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

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


@@ 169,28 136,27 @@ 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
Limit all lines to a maximum of 80 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
.. _bug tracker: https://todo.sr.ht/~cnx/palace
.. _mailing list: https://lists.sr.ht/~cnx/palace
.. _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/
.. _tox: https://tox.readthedocs.io
.. _pytest: https://docs.pytest.org
.. _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/
.. _git-send-email: https://git-send-email.io
.. _tag: https://git-scm.com/docs/git-tag
.. _PyPI: https://pypi.org
.. _twine: https://twine.readthedocs.io
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
.. _Octave: https://wiki.octave.org/C%2B%2B_style_guide
.. _documenting: https://devguide.python.org/documenting/#style-guide

M docs/source/copying.rst => docs/source/copying.rst +7 -9
@@ 48,16 48,15 @@ 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.
The wheels are build on builds.sr.ht_ using cibuildwheel_,
which makes building extension modules much less of a painful experience.

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/
.. _pip: https://pip.pypa.io
.. _Alure: https://github.com/kcat/alure
.. _OpenAL Soft: https://kcat.strangesoft.net/openal.html
.. _Vorbis: https://xiph.org/vorbis/


@@ 68,8 67,7 @@ extreamly quickly to obsolete Cython-related issues.
.. _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/
.. _Cython: https://cython.org
.. _builds.sr.ht: https://builds.sr.ht/~cnx/palace
.. _cibuildwheel: https://cibuildwheel.readthedocs.io
.. _Sphinx: https://www.sphinx-doc.org

M docs/source/index.rst => docs/source/index.rst +2 -4
@@ 28,10 28,8 @@ following :pep:`8#naming-conventions` (``PascalCase.snake_case``).
   :caption: Quick Navigation
   :hidden:

   Python Package Index <https://pypi.org/project/palace/>
   Travis CI Build <https://travis-ci.com/github/McSinyx/palace>
   AppVeyor Build <https://ci.appveyor.com/project/McSinyx/palace>
   GitHub Repository <https://github.com/McSinyx/palace>
   SourceHut Project <https://sr.ht/~cnx/palace>
   Python Package Index <https://pypi.org/project/palace>
   Matrix Chat Room <https://matrix.to/#/#palace-dev:matrix.org>

Indices and Tables

M docs/source/installation.rst => docs/source/installation.rst +5 -5
@@ 14,9 14,9 @@ Palace can be installed from PyPI::

   pip install palace

Wheel distributions are built exclusively for amd64.  Currently, only GNU/Linux
and macOS are properly supported. If you want to help packaging for Windows,
please see `GH-1`_ on our issues tracker on GitHub.
Wheel distributions are built exclusively for GNU/Linux on amd64.
If you want to help packaging for other platforms, please reach out
on our `mailing list`_.

From source
-----------


@@ 26,12 26,12 @@ 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
   git clone https://git.sr.ht/~cnx/palace
   pip install palace/

.. _CPython: https://www.python.org/
.. _pip: https://pip.pypa.io/en/latest/
.. _GH-1: https://github.com/McSinyx/palace/issues/1
.. _mailing list: https://lists.sr.ht/~cnx/palace
.. _alure: https://github.com/kcat/alure
.. _CMake: https://cmake.org/
.. _git: https://git-scm.com/

D docs/source/templates/quicknav.html => docs/source/templates/quicknav.html +0 -31
@@ 1,31 0,0 @@
<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>
  <li class="toctree-l1">
    <a class="reference external"
       href="https://matrix.to/#/#palace-dev:matrix.org">
      Matrix Chat Room
    </a>
  </li>
</ul>

M docs/source/tutorial/source.rst => docs/source/tutorial/source.rst +1 -1
@@ 79,4 79,4 @@ drier air.
   src.air_absorption_factor = 0  # dry air (default)

.. _in our repository:
   https://github.com/McSinyx/palace/blob/master/examples/palace-hrtf.py
   https://git.sr.ht/~cnx/palace/tree/main/examples/palace-hrtf.py

M setup.cfg => setup.cfg +3 -3
@@ 1,20 1,20 @@
[metadata]
name = palace
version = 0.2.3
url = https://mcsinyx.github.io/palace
version = 0.2.4
url = https://mcsinyx.gitlab.io/palace
author = Nguyễn Gia Phong
author_email = mcsinyx@disroot.org
classifiers =
    Development Status :: 4 - Beta
    Intended Audience :: Developers
    License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
    Operating System :: MacOS
    Operating System :: POSIX :: Linux
    Programming Language :: C++
    Programming Language :: Cython
    Programming Language :: Python :: 3.6
    Programming Language :: Python :: 3.7
    Programming Language :: Python :: 3.8
    Programming Language :: Python :: 3.9
    Programming Language :: Python :: 3 :: Only
    Topic :: Multimedia :: Sound/Audio
    Topic :: Software Development :: Libraries