Merge pull request #114 from jmbhughes/main

adds documentation on CSV loading

docs/user-guide/fixedlength.rst

@@ -33,16 +33,8 @@ The following code defines a simple fixed length packet
    ])
 
 Note that the CCSDS header need not be included as it is included by default.
-A packet need not be defined in code.
-It can also be defined in a text file.
-For example,
 
-With this file, it is then possible to define the packet object with
-
-.. code-block:: python
-
-   import ccsdspy
-   pkt = ccsdspy.FixedLength.from_file('packet_definition.csv')
+Alternatively, fixed length packets can be :ref:`loaded from a CSV file <loadfile>`.
 
 Parsing a file
 ==============

docs/user-guide/index.rst

@@ -14,5 +14,6 @@ For more details checkout the :ref:`reference`.
    packetfields
    fixedlength
    variablelength
+   loadfile
    converters
    utils

docs/user-guide/loadfile.rst

@@ -0,0 +1,86 @@
+.. _loadfile:
+
+******************************************
+Loading Packet Definitions from a CSV File
+******************************************
+
+Overview
+=========
+
+:ref:`fixed` can be loaded from a CSV (comma separated value) file.
+This is an alternative method for defining packet layouts which may be desirable to some users,
+and is currently undergoing development. The syntax for loading from a CSV file is:
+
+.. code-block:: python
+
+   import ccsdspy
+   pkt = ccsdspy.FixedLength.from_file('packet_definition.csv')
+
+The only requirement is that the CSV is structured as either the :ref:`threecolumn`
+or :ref:`fourcolumn`. At the moment, :ref:`variable` cannot be loaded from a CSV file.
+
+.. contents::
+   :depth: 2
+
+.. _threecolumn:
+
+Basic Layout (Three Columns)
+============================
+
+The basic CSV layout has columns for `name`, `data_type`, and `bit_length`. The first row of the CSV should be a
+header line where the columns are named. Subsequent rows encode packet fields. This format is appropriate if the CSV
+defines all the packets one after another without skipping any. The three column format automatically
+calculates the bit offsets assuming that the packet order is correct. See the :ref:`fourcolumn` format
+for more flexibility.
+
+.. csv-table:: Basic Layout CSV
+   :file: ../../ccsdspy/tests/data/packet_def/simple_csv_3col.csv
+   :widths: 30, 30, 30
+   :header-rows: 1
+
+When the example above is loaded, five `~ccsdspy.PacketField` objects are defined
+with varying names, data types, and bit lengths. To create a `~ccsdspy.PacketArray` instead, define the data type with
+both the type and array shape.
+
+.. csv-table:: Basic Layout CSV with `~ccsdspy.PacketArray`
+   :file: ../../ccsdspy/tests/data/packet_def/simple_csv_3col_with_array.csv
+   :widths: 30, 30, 30
+   :header-rows: 1
+
+In the example above, `VOLTAGE` would instead be a `~ccsdspy.PacketArray` of type `int` with shape `(12, 24)`.
+
+.. _fourcolumn:
+
+Extended Layout (Four Columns)
+==============================
+
+The extended CSV layout has columns for `name`, `data_type`, `bit_length`, and `bit_offset`.
+The first row of the CSV should be a header line where the columns are named. Subsequent rows encode packet fields.
+This format allows more flexibility than the basic layout because bit offsets are explicitly defined instead
+of automatically calculated. Due to this, some packet fields can be skipped
+since the bit offset indicates exactly where the packet begins.
+
+.. csv-table:: Extended Layout CSV
+   :file: ../../ccsdspy/tests/data/packet_def/simple_csv_4col.csv
+   :widths: 30, 30, 30, 30
+   :header-rows: 1
+
+When the example above is loaded, five `~ccsdspy.PacketField` objects are defined
+with varying names, data types, and bit lengths. To create a `~ccsdspy.PacketArray` instead, define the data type with
+both the type and array shape.
+
+.. csv-table:: Extended Layout CSV with `~ccsdspy.PacketArray`
+   :file: ../../ccsdspy/tests/data/packet_def/simple_csv_4col_with_array.csv
+   :widths: 30, 30, 30, 30
+   :header-rows: 1
+
+In the example above, `SHSCOARSE` would instead be a `~ccsdspy.PacketArray` of type `uint` with shape `(4)`.
+
+Limitations of the CSV format
+=============================
+
+The CSV format is in development and is currently limited. The limitations are:
+
+* the byte order cannot be defined in the CSV.
+* the array order and byte order cannot be defined in the CSV.
+* :ref:`variable` cannot currently be loaded from a CSV file.