From 00945da22706aa15309a9bdafd229de5e86e6735 Mon Sep 17 00:00:00 2001 From: Pierre-Etienne Bougue Date: Mon, 22 Jun 2020 18:18:23 +0200 Subject: [PATCH] [doc] move internal doc files and links * move `src/documentation/` -> `documentation/` * rename `common.md` -> `common_ntfs_rules.md` (and change links) * add links into binaries readmes toward relevant specs --- .../common_ntfs_rules.md | 2 +- .../deprecated_ntfs_fares_reading.md | 2 +- .../deprecated_ntfs_fares_writing.md | 0 .../fares_internal_format.md | 0 .../gtfs_to_ntfs_specs.md | 25 +++++++++--------- .../netex_france_point_on_route.png | Bin ...france_point_on_route_vehicle_journeys.png | Bin .../ntfs_to_gtfs_specs.md | 0 .../ntfs_to_netex_france_specs.md | 0 gtfs2netexfr/README.md | 10 +++++++ gtfs2ntfs/README.md | 10 ++++++- ntfs2gtfs/README.md | 8 ++++++ ntfs2netexfr/README.md | 8 ++++++ ntfs2ntfs/README.md | 6 +++++ restrict-validity-period/README.md | 6 +++++ 15 files changed, 62 insertions(+), 15 deletions(-) rename src/documentation/common.md => documentation/common_ntfs_rules.md (99%) rename {src/documentation => documentation}/deprecated_ntfs_fares_reading.md (99%) rename {src/documentation => documentation}/deprecated_ntfs_fares_writing.md (100%) rename {src/documentation => documentation}/fares_internal_format.md (100%) rename {src/documentation => documentation}/gtfs_to_ntfs_specs.md (97%) rename {src/documentation => documentation}/netex_france_point_on_route.png (100%) rename {src/documentation => documentation}/netex_france_point_on_route_vehicle_journeys.png (100%) rename {src/documentation => documentation}/ntfs_to_gtfs_specs.md (100%) rename {src/documentation => documentation}/ntfs_to_netex_france_specs.md (100%) diff --git a/src/documentation/common.md b/documentation/common_ntfs_rules.md similarity index 99% rename from src/documentation/common.md rename to documentation/common_ntfs_rules.md index b0f23a0a5..c9e479f81 100644 --- a/src/documentation/common.md +++ b/documentation/common_ntfs_rules.md @@ -130,7 +130,7 @@ The following rules apply to every converter, unless otherwise explicitly specif * lines with continuous circulation are indicated by default with an opening at 00:00 and a closing at 23:59. ### Conflicting identifiers -The model will raise a critical error if identifiers of 2 objects of the same type are identicals. +The model will raise a critical error if identifiers of 2 objects of the same type are identical. For example: * if 2 datasets have the same identifier * if 2 lines have the same identifier diff --git a/src/documentation/deprecated_ntfs_fares_reading.md b/documentation/deprecated_ntfs_fares_reading.md similarity index 99% rename from src/documentation/deprecated_ntfs_fares_reading.md rename to documentation/deprecated_ntfs_fares_reading.md index 7955ad268..679f944ea 100644 --- a/src/documentation/deprecated_ntfs_fares_reading.md +++ b/documentation/deprecated_ntfs_fares_reading.md @@ -31,4 +31,4 @@ In the following, the NTM properties that are not specified are ignored and not | ticket_id | | | Id of the `Ticket` to which this `OD Rule` is applied. | | origin_stop_area_id | od_fares.csv | Origin ID | Id of the origin stop_area in Navitia when the value of "Origin mode" is set to `stop`. Otherwise, the rule and the corresponding ticket is ignored. | | destination_stop_area_id | od_fares.csv | Destination ID | Id of the destination stop_area in Navitia when the value of "Destination mode" is set to `stop`. Otherwise, the rule and the corresponding ticket is ignored. | -| physical_mode_id | fares.csv | après changement | Id of the physical mode in Navitia associated to this `OD Rule` when the value of "condition globale" is set to `with_changes`. | \ No newline at end of file +| physical_mode_id | fares.csv | après changement | Id of the physical mode in Navitia associated to this `OD Rule` when the value of "condition globale" is set to `with_changes`. | diff --git a/src/documentation/deprecated_ntfs_fares_writing.md b/documentation/deprecated_ntfs_fares_writing.md similarity index 100% rename from src/documentation/deprecated_ntfs_fares_writing.md rename to documentation/deprecated_ntfs_fares_writing.md diff --git a/src/documentation/fares_internal_format.md b/documentation/fares_internal_format.md similarity index 100% rename from src/documentation/fares_internal_format.md rename to documentation/fares_internal_format.md diff --git a/src/documentation/gtfs_to_ntfs_specs.md b/documentation/gtfs_to_ntfs_specs.md similarity index 97% rename from src/documentation/gtfs_to_ntfs_specs.md rename to documentation/gtfs_to_ntfs_specs.md index 13becb790..2acbf8946 100644 --- a/src/documentation/gtfs_to_ntfs_specs.md +++ b/documentation/gtfs_to_ntfs_specs.md @@ -9,14 +9,14 @@ specification, the conversion should stop immediately with an error, unless otherwise specified. At the end of the conversion, a sanitizing operation is started on the final -model. See [common.md](common.md) for more information. +model. See [common NTFS rules] for more information. ### Prepending data -As explained in [common.md](common.md), a prefix is added to all identifiers during the conversion in order to guarantee uniqueness among objects IDs. +As explained in [common NTFS rules], a prefix is added to all identifiers during the conversion in order to guarantee uniqueness among objects IDs. In the following chapters, identifiers may be prepend with this _prefix_ using this pattern : **\:**. The use of this specific pattern is shown explicitly using the value **ID** in the column _Constraint_ in the tables below. -In addition, the NTFS format introduces 2 objects to enable the manipulation of several datasets: contributors and datasets. Those two objects are described in [common.md](common.md). +In addition, the NTFS format introduces 2 objects to enable the manipulation of several datasets: contributors and datasets. Those two objects are described in [common NTFS rules]. Two parameters can be specified in the configuration of the converter in order to determine if on demand transport (ODT) data should be considered when reading the input GTFS (in particular, when [reading the stop_times.txt file](#reading-stop_timestxt)): * a boolean parameter `odt`, by default set to `false`, indicating if the GTFS should be considered as containing ODT information @@ -148,7 +148,7 @@ The standard values of the `route_type` field are directly mapped to the NTFS mo (2) The commercial_mode ID are standardized when converting from GTFS. This value must not be prefixed. All `physical_mode` are enhanced with CO2 emission and fallback modes, following -the documentation in [common.md](common.md#co2-emissions-and-fallback-modes). +the documentation in [common NTFS rules](common_ntfs_rules.md#co2-emissions-and-fallback-modes). #### Loading Routes A Route is created for each direction of existing trips. If 2 routes with the @@ -275,14 +275,14 @@ For exemple : (3) A comment associated to the stop_time is created in the files comments.txt and comment_links.txt as follows: -| NTFS file | NTFS field | Constraint | Value/Note | -| ----------------- | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| comments.txt | comment_id | Required | The value of stop_time_id is used as the concatenation of trip_id and stop_sequence separated by `-`. Note that this field is prefixed as explained in [common.md](common.md). | -| comments.txt | comment_type | Optional | `on_demand_transport` | -| comments.txt | comment_name | Required | The message set for the parameter `odt_comment`. | -| comment_links.txt | object_id | Required | The value of stop_time_id is used as the concatenation of trip_id and stop_sequence separated by `-`. Note that this field is prefixed as explained in [common.md](common.md). | -| comment_links.txt | object_type | Required | `stop_time` | -| comment_links.txt | comment_id | Required | The value of stop_time_id is used as the concatenation of trip_id and stop_sequence separated by `-`. Note that, as this field references the comment in file comments.txt, it should be prefixed as explained in [common.md](common.md). | +| NTFS file | NTFS field | Constraint | Value/Note | +| ----------------- | ------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| comments.txt | comment_id | Required | The value of stop_time_id is used as the concatenation of trip_id and stop_sequence separated by `-`. Note that this field is prefixed as explained in [common NTFS rules]. | +| comments.txt | comment_type | Optional | `on_demand_transport` | +| comments.txt | comment_name | Required | The message set for the parameter `odt_comment`. | +| comment_links.txt | object_id | Required | The value of stop_time_id is used as the concatenation of trip_id and stop_sequence separated by `-`. Note that this field is prefixed as explained in [common NTFS rules]. | +| comment_links.txt | object_type | Required | `stop_time` | +| comment_links.txt | comment_id | Required | The value of stop_time_id is used as the concatenation of trip_id and stop_sequence separated by `-`. Note that, as this field references the comment in file comments.txt, it should be prefixed as explained in [common NTFS rules]. | ### Reading transfers.txt * If 2 transfers with the same ID are specified, the conversion should stop @@ -333,3 +333,4 @@ A complementary `object_code` is added to each new trip with the following prope [GTFS]: https://gtfs.org/reference/static [NTFS]: https://github.com/CanalTP/ntfs-specification/blob/master/ntfs_fr.md +[common NTFS rules]: common_ntfs_rules.md diff --git a/src/documentation/netex_france_point_on_route.png b/documentation/netex_france_point_on_route.png similarity index 100% rename from src/documentation/netex_france_point_on_route.png rename to documentation/netex_france_point_on_route.png diff --git a/src/documentation/netex_france_point_on_route_vehicle_journeys.png b/documentation/netex_france_point_on_route_vehicle_journeys.png similarity index 100% rename from src/documentation/netex_france_point_on_route_vehicle_journeys.png rename to documentation/netex_france_point_on_route_vehicle_journeys.png diff --git a/src/documentation/ntfs_to_gtfs_specs.md b/documentation/ntfs_to_gtfs_specs.md similarity index 100% rename from src/documentation/ntfs_to_gtfs_specs.md rename to documentation/ntfs_to_gtfs_specs.md diff --git a/src/documentation/ntfs_to_netex_france_specs.md b/documentation/ntfs_to_netex_france_specs.md similarity index 100% rename from src/documentation/ntfs_to_netex_france_specs.md rename to documentation/ntfs_to_netex_france_specs.md diff --git a/gtfs2netexfr/README.md b/gtfs2netexfr/README.md index 78dcb198a..c65bcd4c8 100644 --- a/gtfs2netexfr/README.md +++ b/gtfs2netexfr/README.md @@ -40,3 +40,13 @@ gtfs2netexfr --input /path/to/gtfs/folder/ --output /path/to/netexfr/ --particip export; it is exported in each NeTEx file Get more information about the available options with `--help`. + +## Specifications + +As NTFS is the pivot format for conversion, [common NTFS rules] is useful.
+For input, see [GTFS to NTFS specifications].
+For output, see [NTFS to NeTEx-France specifications]. + +[common NTFS rules]: ../documentation/common_ntfs_rules.md +[GTFS to NTFS specifications]: ../documentation/gtfs_to_ntfs_specs.md +[NTFS to NeTEx-France specifications]: ../documentation/ntfs_to_netex_france_specs.md diff --git a/gtfs2ntfs/README.md b/gtfs2ntfs/README.md index 51760746f..718f4a123 100644 --- a/gtfs2ntfs/README.md +++ b/gtfs2ntfs/README.md @@ -32,7 +32,7 @@ Get more information about the available options with `--help`. NTFS needs a `Dataset` and a `Contributor`. Default ones are provided by the command but you can pass a json file that contains some information for creating a `Dataset` and a `Contributor` as -explained in the [documentation](../src/documentation/common.md). +explained in the [common NTFS rules]. ```json { @@ -49,3 +49,11 @@ explained in the [documentation](../src/documentation/common.md). } } ``` + +## Specifications + +As NTFS is the pivot format for conversion, [common NTFS rules] is useful.
+For input and output, see [GTFS to NTFS specifications]. + +[common NTFS rules]: ../documentation/common_ntfs_rules.md +[GTFS to NTFS specifications]: ../documentation/gtfs_to_ntfs_specs.md diff --git a/ntfs2gtfs/README.md b/ntfs2gtfs/README.md index 5d695356d..b658f2e2b 100644 --- a/ntfs2gtfs/README.md +++ b/ntfs2gtfs/README.md @@ -26,3 +26,11 @@ ntfs2gtfs --input /path/to/ntfs/folder/ --output /path/to/gtfs/ * `--output` is the path to a folder where the GTFS will be exported Get more information about the available options with `--help`. + +## Specifications + +As NTFS is the pivot format for conversion, [common NTFS rules] is useful.
+For input and output, see [NTFS to GTFS specifications]. + +[common NTFS rules]: ../documentation/common_ntfs_rules.md +[NTFS to GTFS specifications]: ../documentation/ntfs_to_gtfs_specs.md diff --git a/ntfs2netexfr/README.md b/ntfs2netexfr/README.md index c25a3fd65..157c94b6a 100644 --- a/ntfs2netexfr/README.md +++ b/ntfs2netexfr/README.md @@ -40,3 +40,11 @@ ntfs2netexfr --input /path/to/ntfs/folder/ --output /path/to/netexfr/ --particip export; it is exported in each NeTEx file Get more information about the available options with `--help`. + +## Specifications + +As NTFS is the pivot format for conversion, [common NTFS rules] is useful.
+For input and output, see [NTFS to NeTEx-France specifications]. + +[common NTFS rules]: ../documentation/common_ntfs_rules.md +[NTFS to NeTEx-France specifications]: ../documentation/ntfs_to_netex_france_specs.md diff --git a/ntfs2ntfs/README.md b/ntfs2ntfs/README.md index 4376f1c7b..0c2778a97 100644 --- a/ntfs2ntfs/README.md +++ b/ntfs2ntfs/README.md @@ -24,3 +24,9 @@ ntfs2ntfs --input /path/to/ntfs/folder/ --output /path/to/ntfs/ * `--output` is the path to a folder where the NTFS will be exported Get more information about the available options with `--help`. + +## Specifications + +As NTFS is the pivot format for data processing, [common NTFS rules] is useful. + +[common NTFS rules]: ../documentation/common_ntfs_rules.md diff --git a/restrict-validity-period/README.md b/restrict-validity-period/README.md index 992416d78..1fa2f90a4 100644 --- a/restrict-validity-period/README.md +++ b/restrict-validity-period/README.md @@ -27,3 +27,9 @@ restrict-validity-period --input /path/to/ntfs/folder/ --output /path/to/ntfs/ - * `--end-validity-date` is the end of the desired validity period (included) Get more information about the available options with `--help`. + +## Specifications + +As NTFS is the pivot format for data processing, [common NTFS rules] is useful. + +[common NTFS rules]: ../documentation/common_ntfs_rules.md