Merge pull request #911 from ibi-group/new-documentation

✨ New Documentation (No large files!) ✨
ibi-group · Dec 14, 2023 · fc4a7c9 · fc4a7c9
2 parents 1010325 + 6be9132
commit fc4a7c9
Show file tree

Hide file tree

Showing 60 changed files with 507 additions and 356 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -1,4 +1,4 @@
 # See https://help.github.com/articles/about-codeowners/
 
-# An IBI Group OTP/Data Tools member is required to approve PR merges
+# An Arcadis OTP/TRANSIT-data-tools member is required to approve PR merges
 * @ibi-group/otp-data-tools
diff --git a/docs/dev/api_interaction.md b/docs/dev/api_interaction.md
@@ -1,4 +1,4 @@
-# API Interaction Transcript
+# API Interaction
 The following is a set of instructions on API calls needed to upload and validate
 a feed, wait for the tasks' completion, and then browse its contents. All of the
 endpoints needed to load and process a GTFS file are REST-based. The endpoints

diff --git a/docs/dev/deployment.md b/docs/dev/deployment.md
@@ -110,7 +110,7 @@ Auth0 is used for authentication in the application. If you don't need authentic
         - Application level
             - Allowed Callback URLs
             - Allowed Origins (CORS)
-    - keep all other default settings
+    - Keep all other default settings
 
 #### Creating your first user
 Create your first Auth0 user through Auth0 web console (Users > Create User). In
@@ -141,32 +141,32 @@ AUTH0_DOMAIN: your-auth0-domain.auth.com
 AUTH0_CLIENT_ID: your-auth0-client-id
 ```
 
-Update the following properties in `datatools-server` `env.yml` to reflect the secure Auth0 application settings.
+Update the following properties in `datatools-server` and `env.yml` to reflect the secure Auth0 application settings.
 
-**Note:** for older Auth0 accounts/tenants, it is possible to use the Auth0 secret token, which uses the HS256 algorithm, but newer Auth0 tenants will need to specify the absolute path of their `.pem` file in the `AUTH0_PUBLIC_KEY` property. This public key only needs to be downloaded one time for your Auth0 tenant at `https://[your_domain].auth0.com/pem`.
+**Note:** For older Auth0 accounts or tenants, it is possible to use the Auth0 secret token with the HS256 algorithm is possible. However, newer Auth0 tenants will need to specify the absolute path of their `.pem` file in the `AUTH0_PUBLIC_KEY` property. This public key only needs to be downloaded one time for your Auth0 tenant at `https://[your_domain].auth0.com/pem`.
 
 ```yaml
 AUTH0_SECRET: your-auth0-client-secret # used for pre-September 2017 Auth0 accounts
 AUTH0_PUBLIC_KEY: /location/of/auth0-account.pem # used for post-September 2017 Auth0 accounts
 AUTH0_TOKEN: your-auth0-api-token
 ```
 
-**Note**: to generate the `api_token`, go to Documentation > Management API. After adding scopes, your token will appear in the input field.
+**Note**: To generate the `api_token`, go to Documentation > Management API. After adding scopes, your token will appear in the input field.
 
-![Auth0 token generator](../img/auth0-token-generator.png)
+<img src="https://datatools-builds.s3.amazonaws.com/docs/auth0/auth0-token-generator.png" style="box-shadow: 3px 3px 3px gray; border-radius: 10px;">
 
 To allow for the creation, deletion and editing of users you must generate a token for the following scopes:
 
 - **users**:
     - read, update, create and delete
 - **users_app_metadata**:
-    - read, update, create and delete`
+    - read, update, create and delete
 
 #### Auth0 Post-Login Action Configuration: making `app_metadata` and `user_metadata` visible via token
 
 If using OIDC-conformant clients/APIs (which appears to be mandatory for new Auth0 tenants), you must set up a custom Auth0 action to add `app_metadata` and `user_metadata` to the user's id token (Note: this is not the default for older, "legacy" Auth0 accounts).
 
-To set up the action, go to Actions > Flows > Login, then under Add action > Custom, click Create Action. Fill in the action name and pick a recommended runtime, and click Create. Modify the function `onExecutePostLogin` as follows, then click Save Draft:
+To set up the action, go to Actions > Flows > Login, then under Add action > Custom, click `Create Action`. Fill in the action name and pick a recommended runtime, and click `Create`. Modify the function `onExecutePostLogin` as follows, then click `Save Draft`:
 
 ```js
 exports.onExecutePostLogin = async (event, api) => {
@@ -177,9 +177,11 @@ exports.onExecutePostLogin = async (event, api) => {
   }
 };
 ```
+If you want the rule to apply only to specific clients, you can retain the conditional block that checks the `context.clientID` value. Otherwise, you can remove this conditional block if it's not needed.
+This rule will ensure that `app_metadata` and `user_metadata` are included in the user's token, as required for OIDC-conformant clients/APIs in new Auth0 tenants.
 
-You can test the action with mock token data using the Test tab. Once ready, click Deploy, then click Back to Flow.
-In the diagram, drag the action between the Start and Complete steps, then click Apply.
+You can test the action with mock token data using the Test tab. Once ready, click `Deploy`, then click `Back to Flow`.
+In the diagram, drag the action between the Start and Complete steps, then click `Apply`.
 You can test that the action is correctly executed by logging-in to datatools with an admin user
 and checking that the Admin functionality is available.
 
@@ -307,6 +309,7 @@ extensions:
 ```
 
 ### Integration with [TransitFeeds](http://transitfeeds.com/)
+**Note**: TransitFeeds is not regularly updated and is being replaced by the [MobilityData Database](https://database.mobilitydata.org/)
 
 Ensure that the `extensions:transitfeeds:enabled` flag is set to `true` in
 `config.yml`, and provide your API key:
@@ -317,4 +320,4 @@ extensions:
     enabled: true
     api: http://api.transitfeeds.com/v1/getFeeds
     key: your-api-key
-```
+```
diff --git a/docs/dev/development.md b/docs/dev/development.md
@@ -1,5 +1,5 @@
 # Development
-These instructions should allow you to get Data Tools / Editor / Catalogue up and running within an integrated development environment, allowing you to work on the code and debug it. We all use IntelliJ so instructions will currently be only for that environment.
+These instructions should allow you to get TRANSIT-data-tools / Editor / Catalogue up and running within an integrated development environment, allowing you to work on the code and debug it. We all use IntelliJ so instructions will currently be only for that environment.
 ## Components
 The system is made up of two different projects:
 

diff --git a/docs/dev/localization.md b/docs/dev/localization.md
@@ -3,7 +3,7 @@
 ## Adding translations for a new language
 To add support for a new language, you need to perform the following steps:
 
-1. Create a new language file in folder `i18`, e.g. by copying the `english.yml`.
+1. Create a new language file in folder `i18n`, e.g. by copying the `english.yml` file.
 2. In the newly created `<new language>.yml`, adapt the first two lines: `_id` should conform to the ISO 639 language code, `_name` to the localized language name.
 3. In `lib/common/util/config.js`, add the import of the new language file at the mark  `// Add additional language files here.` Mind to add an `// $FlowFixMe` hint before the new line to make the linter happy
 4. Translate all messages in the `<new language>.yml` file. Note, that names surrounded by percent characters (`%`) denote parameters and must not be translated.

diff --git a/docs/img/add-fare-zone.png b/docs/img/add-fare-zone.png
diff --git a/docs/img/auth0-token-generator.png b/docs/img/auth0-token-generator.png
diff --git a/docs/img/configure-feed-transformations.png b/docs/img/configure-feed-transformations.png
diff --git a/docs/img/create-project.png b/docs/img/create-project.png
diff --git a/docs/img/create-user.png b/docs/img/create-user.png
diff --git a/docs/img/edit-calendars.png b/docs/img/edit-calendars.png
diff --git a/docs/img/edit-fare-rules.png b/docs/img/edit-fare-rules.png
diff --git a/docs/img/edit-fares.png b/docs/img/edit-fares.png
diff --git a/docs/img/edit-frequencies.png b/docs/img/edit-frequencies.png
diff --git a/docs/img/edit-patterns.png b/docs/img/edit-patterns.png
diff --git a/docs/img/edit-routes.png b/docs/img/edit-routes.png
diff --git a/docs/img/edit-stops.png b/docs/img/edit-stops.png
diff --git a/docs/img/edit-timetables.png b/docs/img/edit-timetables.png
diff --git a/docs/img/feed-profile.png b/docs/img/feed-profile.png
diff --git a/docs/img/feed-transformation-summary.png b/docs/img/feed-transformation-summary.png
diff --git a/docs/img/feed-version-navigator.png b/docs/img/feed-version-navigator.png
diff --git a/docs/img/otp-deployment-diagram.png b/docs/img/otp-deployment-diagram.png
diff --git a/docs/img/password-reset-logged-in.png b/docs/img/password-reset-logged-in.png
diff --git a/docs/img/password-reset-logged-out.png b/docs/img/password-reset-logged-out.png
diff --git a/docs/img/pattern-add-stop.png b/docs/img/pattern-add-stop.png
diff --git a/docs/img/pattern-insert-stop.png b/docs/img/pattern-insert-stop.png
diff --git a/docs/img/pattern-shape-panel.png b/docs/img/pattern-shape-panel.png
diff --git a/docs/img/pattern-stop-order.png b/docs/img/pattern-stop-order.png
diff --git a/docs/img/pattern-stop-toolbar.png b/docs/img/pattern-stop-toolbar.png
diff --git a/docs/img/project-profile.png b/docs/img/project-profile.png
diff --git a/docs/img/quick-access-toolbar.png b/docs/img/quick-access-toolbar.png
diff --git a/docs/img/schedule-exception.png b/docs/img/schedule-exception.png
diff --git a/docs/img/schedule-toolbar.png b/docs/img/schedule-toolbar.png
diff --git a/docs/img/select-trips.png b/docs/img/select-trips.png
diff --git a/docs/img/timetable-selector.png b/docs/img/timetable-selector.png
diff --git a/docs/img/user-admin.png b/docs/img/user-admin.png
diff --git a/docs/img/user-profile.png b/docs/img/user-profile.png
diff --git a/docs/img/view-all-stops.png b/docs/img/view-all-stops.png
diff --git a/docs/index.md b/docs/index.md
@@ -1,7 +1,7 @@
-# IBI Transit Data Tools (TRANSIT-data-tools)
+# Arcadis TRANSIT-data-tools
 
-The IBI Transit Data Tools suite provides web-based tools for creating, managing, evaluating, and publishing transit data, specifically data stored in the General Transit Feed Specification (GTFS) format.
+The Arcadis TRANSIT-data-tools suite provides web-based tools for creating, managing, evaluating, and publishing transit data, specifically data stored in the General Transit Feed Specification (GTFS) format.
 
-![screenshot](img/feed-profile.png)
+![feed-profile](https://datatools-builds.s3.amazonaws.com/docs/intro/feed-profile.png)
 
-To get started, click a topic from the table of contents on the left pane.
+To get started, select a topic from the table of contents on the left pane.
diff --git a/docs/style.css b/docs/style.css
@@ -1,12 +1,36 @@
-img[alt=screenshot] { width: 100%; }
+body {
+  font-family: Arial, Helvetica, sans-serif;
+}
 
-/*Ignore first heading in page in TOC list*/
-li.toctree-l3:first-child {
-    display: none;
+h1, h2, h3 {
+  color: #015f97;
+  font-family: Arial, Helvetica, sans-serif;
 }
 
 .img-center {
-  width: 300px;
   margin-left: auto;
   margin-right: auto;
+  width: 300px;
+}
+
+/* Make all images responsive */
+img {
+  display: block;
+  margin: auto;
+}
+
+img[alt=screenshot] {
+  width: 100%;
+}
+
+/* Center all iframes */
+iframe {
+  display: block;
+  margin: 12px auto;
 }
+
+/* Ignore the first heading in the page in TOC list */
+li.toctree-l3:first-child {
+  display: none;
+}
+
diff --git a/docs/user/add-deployment-server.md b/docs/user/add-deployment-server.md
@@ -1,29 +1,29 @@
-# Adding an OTP Deployment Server in Data Tools
+# Adding an OTP Deployment Server in TRANSIT-data-tools
 
 Assumptions:
 
-* [X] You are an admin for Data Tools.
+* [X] You are an admin for TRANSIT-data-tools.
 * [X] You have [set up OTP UI and backend servers on AWS](./setting-up-aws-servers.md).
 * [X] You have a private key file (usually ends in `.pem`) to connect to that AWS environment and EC2 servers via ssh.
 
-From `Administration > Deployment servers`, click on `+ Add Server`.
+From `Administration > Deployment servers`, click `+ Add Server`.
 
 ## General Server Properties
 
 | Property | Description |
 |----------|-------------|
 | Name     | A descriptive display name for the server.        |
-| Public URL | The URL where the public can access the Data Tools UI, e.g. `https://otp-mod-ui.ibi-transit.com`. It is typically the  CNAME of the CloudFront mirror of the AWS S3 bucket you created or picked for this deployment.         |
+| Public URL | The URL where the public can access the TRANSIT-data-tools UI, e.g. `https://otp-mod-ui.ibi-transit.com`. It is typically the  CNAME of the CloudFront mirror of the AWS S3 bucket you created or picked for this deployment.         |
 | Internal URLs (Optional) | The URL(s) based on the UI server IP address(es). |
-| S3 bucket name | The name of the AWS S3 bucket you created or picked for this deployment, where Data Tools will share files with the OTP servers. |
+| S3 bucket name | The name of the AWS S3 bucket you created or picked for this deployment, where TRANSIT-data-tools will share files with the OTP servers. |
 | Admin access only? | Check this option to only allow logins from Data Tool admins. |
 | Project specific? (Optional) | Select a project to only allow the GTFS feeds of that project (e.g. within a region) to be deployed to this server. Leave blank to remove the project restriction. |
-|AWS Role|The IAM role that the Data Tools application must assume in order to access AWS resources (e.g., writing to S3 buckets or starting EC2 machines). See [Delegate Third Party Access](../setting-up-aws-servers#delegate-third-party-account-access) for more info.|
+|AWS Role|The IAM role that the TRANSIT-data-tools application must assume in order to access AWS resources (e.g., writing to S3 buckets or starting EC2 machines). See [Delegate Third Party Access](../setting-up-aws-servers#delegate-third-party-account-access) for more info.|
 | Use elastic load balancer (ELB) | **We recommend using an elastic load balancer (ELB)**. Behind the scenes, a new server is initialized and added to the load balancer, and old servers are removed and destroyed without interruption to the user. <br><br>The load balancer also allows instantiating multiple OTP servers on large deployments. (You can start, add, or remove more than one OTP server to the load balancer.)
 
 ## Load Balancer Properties
 
-(Applies to Data Tools versions prior to October 2019.)
+(Applies to TRANSIT-data-tools versions prior to October 2019.)
 
 | Property | Description |
 |----------|-------------|

diff --git a/docs/user/deploying-feeds.md b/docs/user/deploying-feeds.md
@@ -4,7 +4,7 @@ Assumptions:
 
 * [X] You have [loaded a GTFS feed into a project](./managing-projects-feeds.md).
 * [X] You have a deployment server available [(example: AWS)](./add-deployment-server.md).
-* [X] [An osm-lib server has been set up](https://github.com/conveyal/osm-lib) for Data Tools to fetch Open Streets Map (OSM) data.
+* [X] [An osm-lib server has been set up](https://github.com/conveyal/osm-lib) for TRANSIT-data-tools to fetch Open Streets Map (OSM) data.
 
 ## Executing a deployment
 
@@ -13,14 +13,14 @@ To deploy or update GTFS feeds to OTP:
 1. Open a project.
 2. Click on the `Deployments` tab.
 3. (Optional) To create a new deployment, click `+ New Deployment`, enter a name, then press or click Enter.
-4. Click the name of the deployment to execute. A summary of feeds and existing deployments (if available) are shown for your review.
+4. Click on the name of the deployment to execute. A summary of feeds and existing deployments (if available) are shown for your review.
 5. Remove the feeds you don't need from the deployment. For the remaining feeds, select the correct feed version.
 6. In the `OTP Configuration` pane:
  * Select the latest OTP version (the first one in the list).
  * Check `Build graph only` to only generate and output a graph file on EC2 to the S3 server (no OTP server will be running after the graph is generated).
  * The R5 option is not used.
 7. If you select `Custom` under `Build configuration` or `Router configuration`, enter the desired configuration settings.
-8. Click the `Deploy` dropdown at the top of the main pane, then pick the server on which to perform the deployment. Existing deployments on that server will be discarded.
+8. Click on the `Deploy` dropdown at the top of the main pane, then pick the server on which to perform the deployment. Existing deployments on that server will be discarded.
 
 ## Updating the Custom Places Index
 
@@ -32,7 +32,7 @@ The pane also has an option to upload Custom POI CSV files. These files contain
 
 ## Watching deployments take place
 
-After click Deploy, you can watch the deployment progress from the right-hand panel:
+After you click `Deploy`, you can watch the deployment progress from the right-hand panel:
 
 1. The data bundle is uploaded to S3.
 2. One EC2 server is commissioned.

diff --git a/docs/user/editor/calendars.md b/docs/user/editor/calendars.md