api doc now includes class methods

Author: irmen

README.md

@@ -354,6 +354,22 @@ variable number of frames per call.
 > An audio device provided by miniaudio, for audio capture (recording).
 
 
+> *method*  ``close  (self) ``
+
+> > Halt playback or capture and close down the device.
+
+
+> *method*  ``start  (self, callback_generator: Generator[NoneType, Union[bytes, array.array], NoneType]) ``
+
+> > Start the audio device: capture (recording) begins. The recorded audio data is sent to the given
+callback generator as raw bytes. (it should already be started before)
+
+
+> *method*  ``stop  (self) ``
+
+> > Halt playback or capture.
+
+
 *class*  ``DecodeError``
 
 ``DecodeError  (self, /, *args, **kwargs)``
@@ -375,13 +391,40 @@ variable number of frames per call.
 > Query the audio playback and record devices that miniaudio provides
 
 
+> *method*  ``get_captures  (self) -> List[Dict[str, Any]]``
+
+> > Get a list of capture devices and some details about them
+
+
+> *method*  ``get_playbacks  (self) -> List[Dict[str, Any]]``
+
+> > Get a list of playback devices and some details about them
+
+
 *class*  ``DuplexStream``
 
 ``DuplexStream  (self, playback_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, playback_channels: int = 2, capture_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, capture_channels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, playback_device_id: Union[_cffi_backend.CData, NoneType] = None, capture_device_id: Union[_cffi_backend.CData, NoneType] = None) ``
 
 > Joins a capture device and a playback device.
 
 
+> *method*  ``close  (self) ``
+
+> > Halt playback or capture and close down the device.
+
+
+> *method*  ``start  (self, callback_generator: Generator[Union[bytes, array.array], Union[bytes, array.array], NoneType]) ``
+
+> > Start the audio device: playback and capture begin. The audio data for playback is provided by
+the given callback generator, which is sent the recorded audio data at the same time. (it should
+already be started before passing it in)
+
+
+> *method*  ``stop  (self) ``
+
+> > Halt playback or capture.
+
+
 *class*  ``MiniaudioError``
 
 ``MiniaudioError  (self, /, *args, **kwargs)``
@@ -396,6 +439,24 @@ variable number of frames per call.
 > An audio device provided by miniaudio, for audio playback.
 
 
+> *method*  ``close  (self) ``
+
+> > Halt playback or capture and close down the device.
+
+
+> *method*  ``start  (self, callback_generator: Generator[Union[bytes, array.array], int, NoneType]) ``
+
+> > Start the audio device: playback begins. The audio data is provided by the given callback
+generator. The generator gets sent the required number of frames and should yield the sample data as
+raw bytes, a memoryview, an array.array, or as a numpy array with shape (numframes, numchannels).
+The generator should already be started before passing it in.
+
+
+> *method*  ``stop  (self) ``
+
+> > Halt playback or capture.
+
+
 *class*  ``SoundFileInfo``
 
 ``SoundFileInfo  (self, name: str, file_format: str, nchannels: int, sample_rate: int, sample_format: miniaudio.SampleFormat, duration: float, num_frames: int) ``
@@ -410,4 +471,14 @@ variable number of frames per call.
 > An IO stream that reads as a .wav file, and which gets its pcm samples from the provided producer
 
 
+> *method*  ``close  (self) ``
+
+> > Close the file
+
+
+> *method*  ``read  (self, amount: int = 9223372036854775807) -> Union[bytes, NoneType]``
+
+> > Read up to the given amount of bytes from the file.
+
+
 

miniaudio.py

@@ -954,6 +954,7 @@ def __del__(self) -> None:
         self.close()
 
     def start(self, callback_generator: GeneratorTypes) -> None:
+        """Start playback or capture, using the given callback generator (should already been started)"""
         if self.callback_generator:
             raise MiniaudioError("can't start an already started device")
         if not inspect.isgenerator(callback_generator):
@@ -1178,6 +1179,7 @@ def __init__(self, pcm_sample_gen: PlaybackCallbackGeneratorType, sample_rate: i
         lib.drflac_free(data[0])
 
     def read(self, amount: int = sys.maxsize) -> Optional[bytes]:
+        """Read up to the given amount of bytes from the file."""
         if self.bytes_done >= self.max_bytes or not self.sample_gen:
             return b""
         while len(self.buffered) < amount:
@@ -1194,4 +1196,5 @@ def read(self, amount: int = sys.maxsize) -> Optional[bytes]:
         return result
 
     def close(self) -> None:
+        """Close the file"""
         pass

setup.py

@@ -35,27 +35,26 @@ def miniaudio_test_suite():
     )
 
 
-def make_md_docs(modulename: str = "miniaudio", width: int = 100) -> str:
+def make_md_docs(modulename: str = "miniaudio", width: int = 100) -> None:
     import importlib
     import inspect
     module = importlib.import_module(modulename)
     documentable_classes = []
     documentable_enums = []
     documentable_functions = []
-    for name, item in inspect.getmembers(module):
-        if inspect.isclass(item) or inspect.isfunction(item):
-            # consider only non-private classes and functions from the module itself
-            if item.__module__ == modulename and not item.__name__.startswith('_'):
-                if inspect.isclass(item):
-                    if issubclass(item, enum.Enum):
-                        documentable_enums.append((item.__name__, item))
-                    else:
-                        documentable_classes.append((item.__name__, item))
-                elif inspect.isfunction(item):
-                    documentable_functions.append((item.__name__, item))
+    for name, item in inspect.getmembers(module, lambda x: inspect.isclass(x) or inspect.isfunction(x)):
+        # consider only non-private classes and functions from the module itself
+        if item.__module__ == modulename and not item.__name__.startswith('_'):
+            if inspect.isclass(item):
+                if issubclass(item, enum.Enum):
+                    documentable_enums.append((item.__name__, item))
+                else:
+                    documentable_classes.append((item.__name__, item))
+            elif inspect.isfunction(item):
+                documentable_functions.append((item.__name__, item))
     print("\n\n===================  GENERATED API DOCS  =================\n\n")
     for name, func in sorted(documentable_functions):
-        doc = inspect.getdoc(func)
+        doc = inspect.cleandoc(func.__doc__ or "")
         if not doc:
             continue    # don't output if no docstring
         sig = str(inspect.signature(func))
@@ -66,7 +65,7 @@ def make_md_docs(modulename: str = "miniaudio", width: int = 100) -> str:
             print(line)
         print("\n")
     for name, enumk in sorted(documentable_enums):
-        doc = inspect.getdoc(enumk)
+        doc = inspect.cleandoc(enumk.__doc__ or "")
         if not doc:
             continue    # don't output if no docstring
         print("*enum class*  ``{}``".format(name))
@@ -75,7 +74,7 @@ def make_md_docs(modulename: str = "miniaudio", width: int = 100) -> str:
             print(line)
         print("\n")
     for name, klass in sorted(documentable_classes):
-        doc = inspect.getdoc(klass)
+        doc = inspect.cleandoc(klass.__doc__ or "")
         if not doc:
             continue    # don't output if no docstring
         sig = str(inspect.signature(klass.__init__))
@@ -86,4 +85,16 @@ def make_md_docs(modulename: str = "miniaudio", width: int = 100) -> str:
         for line in textwrap.wrap("> "+doc, width):
             print(line)
         print("\n")
+        # methods
+        for mname, method in inspect.getmembers(klass, lambda x: inspect.isfunction(x) or inspect.ismethod(x)):
+            doc = inspect.cleandoc(method.__doc__ or "")
+            if mname.startswith('_') or not doc:
+                continue   # don't output if private or no docstring
+            sig = str(inspect.signature(method))
+            if sig.endswith("-> None"):
+                sig = sig[:-7]
+            print("> *method*  ``{}  {}``\n".format(mname, sig))
+            for line in textwrap.wrap("> > "+doc, width):
+                print(line)
+            print("\n")
     print()