Experimenting with autoapi

CHANGES.md

@@ -1,17 +1,7 @@
-# Version 0.11.0
+# Version 0.10.1
-- Fixed `Mixer.getvolume()` returning outdated value (#126)
+- revert to not throwing an exception on playback buffer underrun;
-- Fixed PCM crashing with some sample formats due to buffer size
+  instead, return -EPIPE like `PCM.read()` does on overrun; #131
-  miscalculation
+- type hints
-- Fixed `PCM.read()` ignoring overruns (regression in 0.10.0)
-- Reverted to `PCM.write()` not throwing an exception on playback buffer
-  underrun; instead, return -EPIPE like `PCM.read()` does on overrun (#130)
-- Added `PCM.avail()` and `PCM.polldescriptors_revents()` functions
-- Added `nominal_bits` and `physical_bits` entries to `PCM.info()`'s
-  return value
-- Added Python type hint file, and adjusted documentation accordingly (#58)
-- Improvements to the examples, in particular isine.py (#42)
-
-Contributions by @ossilator and @viinikv.
 
 # Version 0.10.0
 - assorted improvements (#123 from @ossilator)

alsaaudio.c

@@ -203,6 +203,12 @@ static bool is_value_volume_unit(long unit)
 	return false;
 }
 
+const char * const alsacard_list_doc = R"(.. function:: cards() -> list[str]
+
+   List the available ALSA cards by name. This function is only moderately
+   useful. If you want to see a list of available PCM devices, use :func:`pcms`
+   instead.)";
+
 static PyObject *
 alsacard_list(PyObject *self, PyObject *args)
 {
@@ -3079,7 +3085,7 @@ static PyTypeObject ALSAMixerType = {
 static PyMethodDef alsaaudio_methods[] = {
 	{ "card_indexes", (PyCFunction)alsacard_list_indexes, METH_VARARGS},
 	{ "card_name", (PyCFunction)alsacard_name, METH_VARARGS},
-	{ "cards", (PyCFunction)alsacard_list, METH_VARARGS},
+	{ "cards", (PyCFunction)alsacard_list, METH_VARARGS, alsacard_list_doc },
 	{ "pcms", (PyCFunction)alsapcm_list, METH_VARARGS|METH_KEYWORDS},
 	{ "mixers", (PyCFunction)alsamixer_list, METH_VARARGS|METH_KEYWORDS},
 	{ 0, 0 },

doc/conf.py

@@ -34,7 +34,9 @@ from setup import pyalsa_version
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['autoapi.extension']
+
+autoapi_dirs = ['..']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/libalsaaudio.rst

@@ -34,12 +34,6 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA.
 
    *New in 0.8*
 
-.. function:: cards() -> list[str]
-
-   List the available ALSA cards by name. This function is only moderately
-   useful. If you want to see a list of available PCM devices, use :func:`pcms`
-   instead.
-
 ..
    Omitted by intention due to being superseded by cards():
 

setup.py

@@ -8,7 +8,7 @@ from setuptools import setup
 from setuptools.extension import Extension
 from sys import version
 
-pyalsa_version = '0.11.0'
+pyalsa_version = '0.10.1'
 
 if __name__ == '__main__':
     setup(