Moving the Sphinx-generated API reference into it's package so it is not at top level

docs/source/examples/sdr/index.rst

@@ -6,6 +6,9 @@ SDR Examples
 
 This section contains examples of how to use the SDR package in RIA Toolkit OSS, such as receiving and transmitting signals.
 
+Please note that additional setup is required for most SDR devices after installing the toolkit. 
+For more information, refer to the :ref:`sdr_guides`.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

docs/source/examples/sdr/rx.rst

@@ -47,6 +47,10 @@ In this example, we initialize the `Blade` SDR, configure it to record a signal
     print(f"Total time: {end - start} seconds")
     print(f"Length of the recording: {len(my_rec)} samples")
 
+.. todo::
+
+   Add one extra step to the end of this example to visualize the received signal
+
 Conclusion
 ----------
 

docs/source/index.rst

@@ -7,12 +7,7 @@ RIA Toolkit OSS Documentation
    Introduction <intro/index>
    SDR Guides <sdr_guides/index>
    Examples <examples/index>
-   Datatypes Package <ria_toolkit_oss/datatypes/ria_toolkit_oss.datatypes>
+   RIA Toolkit OSS <ria_toolkit_oss/index>
-   SDR Package <ria_toolkit_oss/ria_toolkit_oss.sdr>
-   IO Package <ria_toolkit_oss/ria_toolkit_oss.io>
-   Transforms Package <ria_toolkit_oss/ria_toolkit_oss.transforms>
-   Utils Package <ria_toolkit_oss/ria_toolkit_oss.utils>
-   Viz Package <ria_toolkit_oss/ria_toolkit_oss.viz>
 
 Indices and tables
 ==================

docs/source/ria_toolkit_oss/index.rst

@@ -0,0 +1,19 @@
+.. _ria_toolkit_oss:
+
+###############
+RIA Toolkit OSS
+###############
+
+This section provides the Sphinx-generated API reference for the RIA Toolkit OSS, including
+class and function signatures, and doctest examples where available.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   Datatypes Package <datatypes/ria_toolkit_oss.datatypes>
+   SDR Package <ria_toolkit_oss.sdr>
+   IO Package <ria_toolkit_oss.io>
+   Transforms Package <ria_toolkit_oss.transforms>
+   Utils Package <ria_toolkit_oss.utils>
+   Viz Package <ria_toolkit_oss.viz>

src/ria_toolkit_oss/datatypes/annotation.py

@@ -57,7 +57,7 @@ class Annotation:
 
     def is_valid(self) -> bool:
         """
-        Check that the annotation sample count is > 0 and the freq_lower_edge<freq_upper_edge.
+        Verify ``sample_count > 0`` and the ``freq_lower_edge < freq_upper_edge``.
 
         :returns: True if valid, False if not.
         """
@@ -96,9 +96,9 @@ class Annotation:
     def __eq__(self, other: Annotation) -> bool:
         return self.__dict__ == other.__dict__
 
-    def to_sigmf_format(self):
+    def to_sigmf_format(self) -> dict:
         """
-        Returns a JSON dictionary representing this annotation formatted to be saved in a .sigmf-meta file.
+        Returns a JSON dictionary representation, formatted for saving in a ``.sigmf-meta`` file.
         """
 
         annotation_dict = {SigMFFile.START_INDEX_KEY: self.sample_start, SigMFFile.LENGTH_INDEX_KEY: self.sample_count}
@@ -119,7 +119,8 @@ class Annotation:
 
 def _is_jsonable(x: Any) -> bool:
     """
-    :return: True if x is JSON serializable, False otherwise.
+    :return: True if ``x`` is JSON serializable, False otherwise.
+    :rtype: bool
     """
     try:
         json.dumps(x)

src/ria_toolkit_oss/datatypes/recording.py

@@ -276,7 +276,13 @@ class Recording:
 
         :return: A new recording with the same metadata and data, with dtype.
 
-        TODO: Add example usage.
+
+        **Examples:**
+
+        .. todo::
+
+           Usage examples coming soon!
+
         """
         # Rather than check for a valid datatype, let's cast and check the result. This makes it easier to provide
         # cross-platform support where the types are aliased across platforms.