Merge pull request #72 from dnv-opensource/71-add-example-output-to-documentation

Add documentation on output files (new page), add links to maritime schema, add links to input/output file pages from usage page.

Author: StephanieKemna

docs/source/index.rst

@@ -13,6 +13,7 @@ Ship Traffic Generator Documentation
    README
    usage
    input_files
+   output_files
    api
    CHANGELOG
    STYLEGUIDE

docs/source/input_files.rst

@@ -1,3 +1,4 @@
+.. _input_files:
 ===========
 Input files
 ===========

docs/source/output_files.rst

@@ -0,0 +1,108 @@
+.. _output_files:
+===========
+Output files
+===========
+
+The Ship Traffic Generator creates output files according to
+the open-source `maritime schema`_ `Traffic Situation`_ format.
+
+.. _maritime schema: https://dnv-opensource.github.io/maritime-schema/
+.. _Traffic Situation: https://dnv-opensource.github.io/maritime-schema/traffic_situation/
+
+Below is one example of an output file created by the Ship Traffic Generator.
+This describes the starting position of the ownship (ship under test)
+and one target ship, and their planned goal positions, for a head-on (HO) encounter.
+Note that the first waypoint is typically set to the initial waypoint.
+The `targetShips` field can contain multiple target ships,
+at different COLREG encounter courses.
+
+Example 1: Output file generated by the Ship Traffic Generator::
+
+    {
+        "version": "0.8.1",
+        "title": "HO",
+        "description": "A head on situation with one target ship.",
+        "ownShip": {
+            "initial": {
+                "position": {
+                    "lon": 10.490654,
+                    "lat": 58.763449
+                },
+                "sog": 10.0,
+                "cog": 0.0,
+                "heading": 0.0,
+                "navStatus": "Under way using engine"
+            },
+            "waypoints": [
+                {
+                    "position": {
+                        "lon": 10.490654,
+                        "lat": 58.763449
+                    }
+                },
+                {
+                    "position": {
+                        "lon": 10.490654,
+                        "lat": 58.8465724
+                    }
+                }
+            ],
+            "static": {
+                "id": 0,
+                "mmsi": 257847600,
+                "name": "BASTO VI",
+                "dimensions": {
+                    "length": 122.0,
+                    "width": 20.0,
+                    "height": 8.0,
+                    "a": 61.0,
+                    "b": 61.0,
+                    "c": 10.0,
+                    "d": 10.0
+                },
+                "shipType": "Passenger"
+            }
+        },
+        "targetShips": [
+            {
+                "initial": {
+                    "position": {
+                        "lon": 10.49680582,
+                        "lat": 58.85500037
+                    },
+                    "sog": 12.1,
+                    "cog": 183.63,
+                    "heading": 183.63,
+                    "navStatus": "Under way using engine"
+                },
+                "waypoints": [
+                    {
+                        "position": {
+                            "lon": 10.49680582,
+                            "lat": 58.85500037
+                        }
+                    },
+                    {
+                        "position": {
+                            "lon": 10.48458595,
+                            "lat": 58.75501409
+                        }
+                    }
+                ],
+                "static": {
+                    "id": 10,
+                    "name": "target_ship_1",
+                    "dimensions": {
+                        "length": 122.0,
+                        "width": 20.0,
+                        "height": 8.0,
+                        "a": 61.0,
+                        "b": 61.0,
+                        "c": 10.0,
+                        "d": 10.0
+                    },
+                    "shipType": "Passenger"
+                }
+            }
+        ]
+    }

docs/source/usage.rst

@@ -26,17 +26,26 @@ Example::
 
     trafficgen gen-situation -s ./data/example_situations_input -o ./data/test_output
 
-Situations
+Input situations
 ~~~~~~~~~~
 When generating situations without specifying where the desired situations (``--situation``) are found, the
 default path, which is ``default=./baseline_situations_input/``, will be used.
+For more information on input files, see :ref:`input_files`.
 
 Baseline situations
 ~~~~~~~~~~~~~~~~~~~
 The baseline situations are a set of generic traffic situations covering head-on, overtaking stand-on/give-way
 and crossing stand-on/give-way encounters. To cover the combination of encounters for 1, 2 and 3 target ships,
-there are in total 55 baseline situations. The input files for generating these situations are found in
-``./baseline_situations_input/``
+there are in total 55 baseline situations.
+
+The input files for generating these situations are found in ``./baseline_situations_input/``
+
+The generated output files for these situations are found in ``./baseline_situations_generated/``
+
+Output situations
+~~~~~~~~~~~~~~~~~
+The generated traffic situations are saved in the specified output folder (``--output``).
+For more information on output files, see :ref:`output_files`.
 
 Plotting
 ~~~~~~~~