Update README.md

CHANGELOG.md

@@ -5,6 +5,7 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e
 
 ## [Unreleased]
 
+* Updated documentation; fix spelling errors, add link to github.io, explain Usage, add note on defining python version with uv sync, add note on activating venv.
 * Fix build issues; move click and click-log to non-dev dependencies.
 * Fix issue with file reading when using non-default paths, and add test for it.
 

README.md

@@ -5,7 +5,10 @@ the tool will generate a set of traffic situations. The traffic situations may b
 
 A paper is written describing the background for the tool and how it works <a href="./docs/source/ICMASS23_verfying_caga_systems.pdf" target="_blank">[paper]</a>
 
+For package documentation, see [https://dnv-opensource.github.io/ship-traffic-generator/](https://dnv-opensource.github.io/ship-traffic-generator/)
+
 ## Installation
+
 To install Ship Traffic Generator, run this command in your terminal:
 ```sh
 pip install trafficgen
@@ -17,11 +20,18 @@ You can check your installation by running:
 uv run trafficgen --help
 ```
 
-See documentation for usage of the Ship Traffic Generator.
+## Usage
+
+For simplest usage, clone this repo, then run ```pip install -e .``` (you may want to do this in a local environment, such as a venv, see an example with `uv` below).
+
+Then run: ```trafficgen gen-situation```.  You can add the option `-v` for visualization.
+
+For further explanations, see the [documentation pages](https://dnv-opensource.github.io/ship-traffic-generator/) of the Ship Traffic Generator.
 
 ## Development Setup
 
 ### Install UV
+
 This project uses `uv` as package manager.
 If you haven't already, install [uv](https://docs.astral.sh/uv), preferably using it's ["Standalone installer"](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_2) method: <br>
 ..on Windows:
@@ -47,6 +57,7 @@ If you don't already have a compatible version installed on your machine, you wa
 uv python install
 ```
 This will install the latest stable version of Python into the uv Python directory, i.e. as a uv-managed version of Python.
+> **Note**: you can also do this after you clone the repo, see below.
 
 Alternatively, and if you want a standalone version of Python on your machine, you can install Python either via `winget`:
 ```sh
@@ -65,12 +76,15 @@ cd ship-traffic-generator
 ```
 
 ### Install dependencies
+
 Run `uv sync -U` to create a virtual environment and install all project dependencies into it:
 ```sh
 uv sync -U
 ```
 > **Note**: Using `--no-dev` will omit installing development dependencies.
 
+> **Note**: You can also define the python environment at the same time, by running for example ```uv sync -U -p 3.12``` to install Python 3.12.
+
 > **Note**: `uv` will create a new virtual environment called `.venv` in the project root directory when running
 > `uv sync` the first time. Optionally, you can create your own virtual environment using e.g. `uv venv`, before running
 > `uv sync`.
@@ -89,13 +103,29 @@ To manually activate the virtual environment, run one of the "known" legacy comm
 ```sh
 .venv\Scripts\activate.bat
 ```
+> **Note**: If you use the cmd terminal in VS Code, it will show this activated venv as (trafficgen) at the start of every line command.
 ..on Linux:
 ```sh
 source .venv/bin/activate
 ```
 
+### Install the package
+
+```sh
+uv pip install -e .
+```
+
+### Test the install
+
+```sh
+pytest .
+```
+
 ### Documentation
-To generate documentation use:
+
+For pre-generated package documentation, see [https://dnv-opensource.github.io/ship-traffic-generator/](https://dnv-opensource.github.io/ship-traffic-generator/)
+
+To generate documentation from the source code, use:
 ```sh
 uv run docs/make.bat html
 ```

docs/source/input_files.rst

@@ -37,13 +37,15 @@ Example 1: Complete specified situation::
         ]
     }
 
-The values are giben in maritime units. The `common_vector` is given in minutes. For radar plotting (plotting vessel positions and relative motions),
+The values are given in maritime units. The `common_vector` is given in minutes. For radar plotting (plotting vessel positions and relative motions),
 the `common_vector` and `vector_time` are used together with ship speed to display where the ship will be in e.g. 10 minutes
 (Common vector is the common time vector used on a radar plot, e.g 10, 15, 20 minutes. The length of the arrow in the plot
 will then be the speed times this time vector).
 Speed and course of the own ship, which is the ship to be tested, are given in knots and degrees, respectively.
-The own ship position is given in latitudinal and longitudinal (degree).
-The reference point is the initial position of own ship.
+The own ship position is given in latitudinal and longitudinal (decimal degrees).
+The reference point, used for conversion to x/y, is the initial position of own ship.
+
+> **Note:** in order to change the location of the traffic situations you are generating, you should change the initial lat/lon position of the own ship, in the input file(s). This is used as the origin point or reference point for all generated traffic situations, i.e. the (0,0) location.
 
 An encounter may be fully described as shown above, but the user may also deside to input less data,
 as demonstrated in Example 2. Desired encounter type is mandatory,
@@ -112,7 +114,7 @@ Example 3: Generate multiple situations using `numSituations`::
         ]
     }
 
-The next example show how it is possible to give a range for the relative bearing between own ship and target ship
+The next example shows how it is possible to give a range for the relative bearing between own ship and target ship.
 
 Example 4: Assign range for `beta`::
 
@@ -137,7 +139,7 @@ Example 4: Assign range for `beta`::
 
 Own ship file
 ~~~~~~~~~~~~~~~
-The own ship file specify the own ship which is the ship to be controlled by the control system under test.
+The own ship file specifies the own ship, which is the ship to be controlled by the control system under test.
 The file is written in JSON format and located in the `src/trafficgen/data/own_ship`::
 
     {
@@ -152,7 +154,7 @@ The file is written in JSON format and located in the `src/trafficgen/data/own_s
         "shipType": "Passenger"
     }
 
-The values are given in maritime units. sogMax is the maximum speed over ground in knots, and the dimensions are given in meters.
+The values are given in maritime units. `sogMax` is the maximum speed over ground in knots, and the dimensions are given in meters.
 
 Target ship files
 ~~~~~~~~~~~~~~~~~
@@ -171,8 +173,8 @@ The file is written in JSON format and is on the following structure::
 
 Encounter settings
 ~~~~~~~~~~~~~~~~~~
-The encounter setting file spesified parameters that are common from
-all encounters. The file is written in JSON format and located in the `src/trafficgen/settings/encounter_settings.json`::
+The encounter setting file specified parameters that are common for all encounters.
+The file is written in JSON format and located in the `src/trafficgen/settings/encounter_settings.json`::
 
     {
         "classification": {
@@ -226,3 +228,4 @@ The `max_meeting_distance` is the maximum meeting distance in nautical miles.
 The `common_vector` is the common time vector used on a radar plot.
 The `evolve_time` is the time in minutes for the situation to evolve.
 The `disable_land_check` is a boolean value that determines if the land check should be disabled or not.
+We refer to the paper for more information on these parameters.