Docs/polish (#112)

* instructions for building the docs locally
* remove nested layer in docs
* resolve docstring format err
* allow tox to run on python3.13

Author: Teque5

docs/source/api.rst

@@ -7,4 +7,12 @@ SigMF API
    :template: custom-module-template.rst
    :recursive:
 
-   sigmf
+   sigmf.apps.convert_wav
+   sigmf.archive
+   sigmf.archivereader
+   sigmf.error
+   sigmf.schema
+   sigmf.sigmf_hash
+   sigmf.sigmffile
+   sigmf.utils
+   sigmf.validate

docs/source/developers.rst

@@ -51,9 +51,22 @@ To autoformat the entire project according to our coding standard:
    $ black sigmf tests # autoformat entire project
    $ isort sigmf tests # format imports for entire project
 
-------
-Issues
-------
+----
+Docs
+----
+
+To build the docs and host locally:
+
+.. code-block:: console
+
+   $ cd docs
+   $ make html
+   $ cd build/html/
+   $ python3 -m http.server
+
+--------------
+Find an Issue?
+--------------
 
 Issues can be addressed by opening an `issue
 <https://github.com/sigmf/sigmf-python/issues>`_ or by forking the project and

docs/source/index.rst

@@ -2,39 +2,39 @@
 Welcome to SigMF!
 =================
 
-**sigmf** is a Python library for working with radio recordings captured in
-``.sigmf`` format according to the `SigMF standard <https://sigmf.org/>`_. It
-offers a *simple* and *intuitive* API for python developers.
+**SigMF** is a Python library for working with radio recordings in
+``.sigmf`` format according to the `SigMF standard <https://sigmf.org/>`_.
+It offers a *simple* and *intuitive* API for Python developers.
 
 ..
-   Note below toolversion & specversion are replaced dynamically during build.
+   Note: The toolversion & specversion below are replaced dynamically during build.
 
-This version |toolversion| of the library coincides with version |specversion|
-of the specification.
+This documentation is for version |toolversion| of the library, which is
+compatible with version |specversion| of the SigMF specification.
 
-Check out the :doc:`quickstart` section for further information, including
-how to :ref:`install` the project.
+To get started, see the :doc:`quickstart` section or learn how to :ref:`install` the library.
 
+-----
 
 .. toctree::
    :maxdepth: 1
+   :caption: Getting Started
    :hidden:
-   :caption: SigMF
 
    quickstart
    advanced
    developers
 
 .. toctree::
    :maxdepth: 1
-   :hidden:
    :caption: Community
+   :hidden:
 
    faq
 
 .. toctree::
    :maxdepth: 1
-   :hidden:
    :caption: API Reference
+   :hidden:
 
-   api
+   api

pyproject.toml

@@ -102,7 +102,7 @@ profile = "black"
 legacy_tox_ini = '''
     [tox]
     skip_missing_interpreters = True
-    envlist = py{37,38,39,310,311,312}
+    envlist = py{37,38,39,310,311,312,313}
 
     [testenv]
     usedevelop = True

sigmf/sigmffile.py

@@ -1000,12 +1000,16 @@ def dtype_info(datatype):
 
 def get_dataset_filename_from_metadata(meta_fn, metadata=None):
     """
-    Parse provided metadata and return the expected data filename. In the case of
-    a metadata only distribution, or if the file does not exist, this will return
-    'None'. The priority for conflicting:
-        1. The file named <stem>.SIGMF_DATASET_EXT if it exists
-        2. The file in the DATASET_KEY field (Non-Compliant Dataset) if it exists
-        3. None (may be a metadata only distribution)
+    Parse provided metadata and return the expected data filename.
+
+    In the case of a metadata-only distribution, or if the file does not exist,
+    this will return ``None``.
+
+    Priority for conflicting datasets:
+
+    1. Use the file named ``<stem>.SIGMF_DATASET_EXT`` if it exists.
+    2. Use the file in the ``DATASET_KEY`` field (non-compliant dataset) if it exists.
+    3. Return ``None`` (may be a metadata-only distribution).
     """
     compliant_filename = get_sigmf_filenames(meta_fn)["data_fn"]
     noncompliant_filename = metadata["global"].get(SigMFFile.DATASET_KEY, None)

tests/test_validation.py

@@ -19,8 +19,7 @@
 
 
 def test_valid_data():
-    """assure the supplied metadata is OK"""
-    invalid_metadata = dict(TEST_METADATA)
+    """ensure the default metadata is OK"""
     SigMFFile(TEST_METADATA).validate()
 
 
@@ -73,7 +72,7 @@ def test_version(self):
 
 
 class FailingCases(unittest.TestCase):
-    """Cases where the validator should throw an exception."""
+    """Cases where the validator should raise an exception."""
 
     def setUp(self):
         self.metadata = dict(TEST_METADATA)