Merge pull request #23 from mgm8/dev

Dev: Adding a reference page to the documentation

README.md

@@ -10,7 +10,7 @@
     <img src="https://img.shields.io/github/license/mgm8/pyngham?style=for-the-badge">
 </a>
 <a href="https://github.com/mgm8/pyngham/actions">
-    <img src="https://img.shields.io/github/workflow/status/mgm8/pyngham/Test?style=for-the-badge">
+    <img src="https://img.shields.io/github/actions/workflow/status/mgm8/pyngham/test.yml?style=for-the-badge">
 </a>
 
 ## Overview

docs/conf.py

@@ -1,7 +1,7 @@
 #
 # conf.py
 # 
-# Copyright (C) 2022, Gabriel Mariano Marcelino - PU5GMA <[email protected]>
+# Copyright (C) 2023, Gabriel Mariano Marcelino - PU5GMA <[email protected]>
 # 
 # This file is part of PyNGHam library.
 # 
@@ -32,14 +32,16 @@
 
 import sphinx_rtd_theme
 
+sys.path.insert(0, os.path.abspath('../'))  # Source code dir relative to this file
+
 # -- Project information -----------------------------------------------------
 
 project = 'pyngham'
-copyright = '2022, Gabriel Mariano Marcelino - PU5GMA'
+copyright = '2023, Gabriel Mariano Marcelino - PU5GMA'
 author = 'Gabriel Mariano Marcelino'
 
 # The full version, including alpha/beta/rc tags
-release = "1.0"
+release = "1.1"
 
 
 # -- General configuration ---------------------------------------------------
@@ -49,6 +51,7 @@
 # ones.
 extensions = [
     'sphinx_rtd_theme',
+    'sphinx.ext.autodoc',       # Core library for html generation from docstrings
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -73,8 +76,3 @@
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']

docs/index.rst

@@ -25,4 +25,5 @@ Contents
    extension
    install
    usage
+   reference
    development

docs/reference.rst

@@ -0,0 +1,23 @@
+*********
+Reference
+*********
+
+On this page, there is a reference to the functions, classes and methods of the PyNGHam library, including a description of each one, and the inputs and outputs.
+
+Main Module
+===========
+
+.. automodule:: pyngham.pyngham
+   :members:
+
+SPP Module
+==========
+
+.. automodule:: pyngham.spp
+   :members:
+
+Extension Module
+================
+
+.. automodule:: pyngham.extension
+   :members:

pyngham/extension.py

@@ -28,6 +28,17 @@
 class ExtPktType(Enum):
     """
     Extension packets types.
+
+    * **DATA**: Generic data packet
+    * **ID**: ID packet
+    * **STAT**: Status packet
+    * **SIMPLEDIGI**: Simple digi packet
+    * **POS**: Position data packet
+    * **TOH**: Time info packet
+    * **DEST**: Destination/receiver callsign
+    * **CMD_REQ**: Command request packet
+    * **CMD_REPLY**: Command reply packet
+    * **REQUEST**: Request packet
     """
     DATA          = 0       # Generic data packet
     ID            = 1       # ID packet
@@ -60,8 +71,10 @@ def get_numpkts(self, d):
         Gets the number of extension packets in a NGHam packet.
 
         :param d: is the packet payload with extension packet(s).
+        :type d: list[int]
 
-        :return The detected number of extension packets.
+        :return: The detected number of extension packets.
+        :rtype: int
         """
         # Go through all sub packets
         start = 0
@@ -82,10 +95,15 @@ def append_pkt(self, pl, typ, data):
         Appends a new extension packet to a NGHam payload.
 
         :param pl: is the packet payload to append an extension packet.
+        :type pl: list[int]
+
         :param typ: is the type of extension packet.
+        :type typ: int
+
         :param data: is the content of the extension packet.
+        :type data: list[int]
 
-        :return The given payload with the extension packet.
+        :return: The given payload with the extension packet.
         """
         if len(pl) + 2 + len(data) > _PYNGHAM_PL_SIZES[-1]:
             return pl
@@ -101,10 +119,16 @@ def append_toh_pkt(self, pl, toh_us, toh_val):
         Adds a TOH extension packet to a NGHam payload.
 
         :param pl is the packet payload to append a TOH packet:
+        :type pl: list[int]
+
         :param toh_us: time of hour in microseconds.
+        :type toh_us: int
+
         :param toh_val: validity.
+        :type toh_val: int
 
-        :return The given payload with the new TOH extension packet.
+        :return: The given payload with the new TOH extension packet.
+        :rtype: list[int]
         """
         data = list()
 
@@ -121,20 +145,46 @@ def append_stat_pkt(self, pl, hw_ver, serial, sw_ver, uptime_s, voltage, temp, s
         Adds an statistic extension packet to a NGHam payload.
 
         :param pl: is the packet payload to append an statistic packet.
+        :type pl: list[int]
+
         :param hw_ver: hardware version ID (10b for company, 6b for product).
+        :type hw_ver: int
+
         :param serial: Serial number.
+        :type serial: int
+
         :param sw_ver: software version ID (4b major, 4b minor, 8b build).
+        :type sw_ver: int
+
         :param uptime_s: time in whole seconds since startup.
+        :type uptime_s: int
+
         :param voltage: input voltage in decivolts (0-25.5)
+        :type voltage: int
+
         :param temp: system temperature in degrees Celsius (-128 to 127).
+        :type temp: int
+
         :param signal: received signal strength in dBm - 200, -200 to 54 (0xFF=N/A).
+        :type signal: int
+
         :param noise: noise floor, same as above.
+        :type noise: int
+
         :param cntr_rx_ok: packets successfully received.
+        :type cntr_rx_ok: int
+
         :param cntr_rx_fix: packets with corrected errors.
+        :type cntr_rx_fix: int
+
         :param cntr_rx_err: packets with uncorrectable errors.
+        :type cntr_rx_err: int
+
         :param cntr_tx: packets sent.
+        :type cntr_tx: int
 
-        :return The given payload with the new statistic extension packet.
+        :return: The given payload with the new statistic extension packet.
+        :rtype: list[int]
         """
         data = list()
 
@@ -168,14 +218,28 @@ def append_pos_pkt(self, pl, latitude, longitude, altitude, sog, cog, hdop):
         Adds a position extension packet to a NGHam payload.
 
         :param pl: is the packet payload to append a position packet.
+        :type pl: list[int]
+
         :param latitude: Latitude in degrees * 10^7
+        :type latitude: int
+
         :param longitude: Longitude in degrees * 10^7
+        :type longitude: int
+
         :param altitude: Altitude in centimeters
+        :type altitude: int
+
         :param sog: Hundreds of meters per second
+        :type sog: int
+
         :param cog: Tenths of degrees
+        :type cog: int
+
         :param hdop: In tenths
+        :type hdop: int
 
-        :return The given payload with the new position extension packet.
+        :return: The given payload with the new position extension packet.
+        :rtype: list[int]
         """
         data = list()
 
@@ -206,10 +270,16 @@ def append_id_pkt(self, pl, call_ssid, sequence):
         :note: Always first in a packet, except when resent by another station.
 
         :param pl: is the packet payload to append an ID packet.
+        :type pl: list[int]
+
         :param call_ssid: 7 x 6 bit (SIXBIT DEC, which is ASCII-32 and limited to 0-64) empty characters padded with 0, 6 bit SSID.
+        :type call_ssid: list[int]
+
         :param sequence: is the packet sequence number, wraps around from 255 to 0.
+        :type sequence: int
 
-        :return The given payload with the new ID extension packet.
+        :return: The given payload with the new ID extension packet.
+        :rtype: list[int]
         """
         data = list()
 
@@ -223,9 +293,13 @@ def append_dest_pkt(self, pl, call_ssid):
         Adds a destination extension packet to a NGHam payload.
 
         :param pl: is the packet payload to append a destination packet.
+        :type pl: list[int]
+
         :param call_ssid: 7 x 6 bit (SIXBIT DEC, which is ASCII-32 and limited to 0-64) empty characters padded with 0, 6 bit SSID.
+        :type call_ssid: list[int]
 
-        :return The given payload with the new destination extension packet.
+        :return: The given payload with the new destination extension packet.
+        :rtype: list[int]
         """
         return self.append_pkt(pl, ExtPktType.DEST.value, call_ssid)
 
@@ -234,8 +308,10 @@ def decode(self, pl):
         Decodes all extension packets in a given NGHam payload.
 
         :param pl: is the NGHam payload to decode.
+        :type pl: list[int]
 
-        :return All found extension packets as a list of dictionaries.
+        :return: All found extension packets as a list of dictionaries.
+        :rtype: dict
         """
         res = list()
 
@@ -277,8 +353,10 @@ def _decode_data_pkt(self, pkt):
         Decodes a data paketc.
 
         :param pkt: is the data packet to decode.
+        :type pkt: list[int]
 
-        :return .
+        :return: None
+        :rtype: None
         """
         pass
 
@@ -287,8 +365,10 @@ def _decode_id_pkt(self, pkt):
         Decodes an ID packet.
 
         :param pkt: is the ID packet to decode.
+        :type pkt: list[int]
 
-        :return .
+        :return: None
+        :rtype: None
         """
         res = {
             "call_ssid":    self.decode_callsign(pkt),
@@ -302,8 +382,10 @@ def _decode_stat_pkt(self, pkt):
         Decodes an status packet.
 
         :param pkt: is the status packet to decode.
+        :type pkt: list[int]
 
-        :return .
+        :return: A dictionary containing the fields of the decoded stat packet.
+        :rtype: dict
         """
         res = {
             "hw_ver":       (pkt[0] << 8) | pkt[1],
@@ -330,8 +412,10 @@ def _decode_pos_pkt(self, pkt):
         Decodes a position packet.
 
         :param pkt: is the position packet to decode.
+        :type pkt: list[int]
 
-        :return .
+        :return: A dictionary containing the fields of the decoded pos packet.
+        :rtype: dict
         """
         res = {
             "latitude":     (pkt[0] << 24) | (pkt[1] << 16) | (pkt[2] << 8) | pkt[3],
@@ -349,8 +433,10 @@ def _decode_toh_pkt(self, pkt):
         Decodes a TOH packet.
 
         :param pkt: is the TOH packet to decode.
+        :type pkt: list[int]
 
-        :return .
+        :return: A dictionary containing the fields of the decoded toh packet.
+        :rtype: dict
         """
         res = {
             "toh_us":       (pkt[0] << 24) | (pkt[1] << 16) | (pkt[2] << 8) | pkt[3],
@@ -364,8 +450,10 @@ def _decode_dest_pkt(self, pkt):
         Decodes a destination packet.
 
         :param pkt: is the destination packet to decode.
+        :type pkt: list[int]
 
-        :return .
+        :return: A dictionary containing the fields of the decoded dest packet.
+        :rtype: dict
         """
         res = {
             "call_ssid":    self.decode_callsign(pkt)
@@ -387,9 +475,13 @@ def encode_callsign(self, callsign, ssid):
         Encodes a given callsign.
 
         :param callsign: is the callsign to encode (ASCII string).
+        :type callsign: str
+
         :param ssid: is the SSID to encode with the callsign (integer).
+        :type ssid: int
 
-        :return The encoded callsign as a list of integers (bytes).
+        :return: The encoded callsign as a list of integers (bytes).
+        :rtype: list[int]
         """
         if (len(callsign) > 7) or (ssid >= 100):
             return list()
@@ -417,8 +509,10 @@ def decode_callsign(self, enc_callsign):
         Decodes a given encoded callsign.
 
         :param enc_callsign: the encoded callsign to decode.
+        :type enc_callsign: list[int]
 
-        :return The decoded callsign as an string.
+        :return: The decoded callsign as an string.
+        :rtype: str
         """
         callsign = str()