From 312c55189ed59290392f52bce9e29ac3baef8d58 Mon Sep 17 00:00:00 2001
From: michael <michael@qoherent.ai>
Date: Fri, 12 Sep 2025 15:36:43 -0400
Subject: [PATCH] Moving the Sphinx-generated API reference into it's package
 so it is not at top level

---
 docs/source/examples/sdr/index.rst          |  3 +++
 docs/source/examples/sdr/rx.rst             |  4 ++++
 docs/source/index.rst                       |  7 +------
 docs/source/ria_toolkit_oss/index.rst       | 19 +++++++++++++++++++
 src/ria_toolkit_oss/datatypes/annotation.py |  9 +++++----
 src/ria_toolkit_oss/datatypes/recording.py  |  8 +++++++-
 6 files changed, 39 insertions(+), 11 deletions(-)
 create mode 100644 docs/source/ria_toolkit_oss/index.rst

diff --git a/docs/source/examples/sdr/index.rst b/docs/source/examples/sdr/index.rst
index 525e983..c563bee 100644
--- a/docs/source/examples/sdr/index.rst
+++ b/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:
diff --git a/docs/source/examples/sdr/rx.rst b/docs/source/examples/sdr/rx.rst
index a314b42..8fd2e3e 100644
--- a/docs/source/examples/sdr/rx.rst
+++ b/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
 ----------
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 1ac0e62..b4a2fa3 100644
--- a/docs/source/index.rst
+++ b/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>
-   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>
+   RIA Toolkit OSS <ria_toolkit_oss/index>
 
 Indices and tables
 ==================
diff --git a/docs/source/ria_toolkit_oss/index.rst b/docs/source/ria_toolkit_oss/index.rst
new file mode 100644
index 0000000..42eb31f
--- /dev/null
+++ b/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>
diff --git a/src/ria_toolkit_oss/datatypes/annotation.py b/src/ria_toolkit_oss/datatypes/annotation.py
index a3aacd2..d565e17 100644
--- a/src/ria_toolkit_oss/datatypes/annotation.py
+++ b/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)
diff --git a/src/ria_toolkit_oss/datatypes/recording.py b/src/ria_toolkit_oss/datatypes/recording.py
index 58ddd49..91dbaf3 100644
--- a/src/ria_toolkit_oss/datatypes/recording.py
+++ b/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.