From f24996537e65d53192c918c3ffbd21b65d3a3576 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adriana=20Ceri=C4=87?= <62163307+AdrianaCeric@users.noreply.github.com> Date: Wed, 29 Nov 2023 17:23:13 -0500 Subject: [PATCH] fix: address pr feedback --- docs/dev/deployment.md | 2 +- docs/index.md | 2 +- docs/user/deploying-feeds.md | 6 +++--- docs/user/editor/fares.md | 1 - .../{introduction.md => getting-started.md} | 0 docs/user/editor/patterns.md | 2 -- docs/user/editor/routes.md | 6 +----- docs/user/editor/schedules.md | 8 +++---- docs/user/editor/stops.md | 16 +++++++++++--- docs/user/introduction.md | 2 +- docs/user/managing-projects-feeds.md | 21 +++++++++++-------- docs/user/managing-users.md | 4 ++-- mkdocs.yml | 4 ++-- 13 files changed, 40 insertions(+), 34 deletions(-) rename docs/user/editor/{introduction.md => getting-started.md} (100%) diff --git a/docs/dev/deployment.md b/docs/dev/deployment.md index f3155f04a..3ffa69f83 100644 --- a/docs/dev/deployment.md +++ b/docs/dev/deployment.md @@ -166,7 +166,7 @@ To allow for the creation, deletion and editing of users you must generate a tok 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 on `Create Action`. Fill in the action name and pick a recommended runtime, and click on `Create`. Modify the function `onExecutePostLogin` as follows, then click Save Draft: ```js exports.onExecutePostLogin = async (event, api) => { diff --git a/docs/index.md b/docs/index.md index 62c3ebcb2..a50a45e35 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,4 +4,4 @@ The IBI Transit Data Tools suite provides web-based tools for creating, managing ![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, click on a topic from the table of contents on the left pane. diff --git a/docs/user/deploying-feeds.md b/docs/user/deploying-feeds.md index 17cb2dba3..8c176710c 100644 --- a/docs/user/deploying-feeds.md +++ b/docs/user/deploying-feeds.md @@ -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 on `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/fares.md b/docs/user/editor/fares.md index 2def5b1d4..dd4aff2bf 100644 --- a/docs/user/editor/fares.md +++ b/docs/user/editor/fares.md @@ -1,6 +1,5 @@ # Fares -## Terminology ### Fare attributes Fare attributes describe the basic information about a fare including the price, currency type and transfer information. See the [GTFS specification fare attribute reference](https://gtfs.org/schedule/reference/#fare_attributestxt) for more information. diff --git a/docs/user/editor/introduction.md b/docs/user/editor/getting-started.md similarity index 100% rename from docs/user/editor/introduction.md rename to docs/user/editor/getting-started.md diff --git a/docs/user/editor/patterns.md b/docs/user/editor/patterns.md index 0ff2d50f6..a653ee60f 100644 --- a/docs/user/editor/patterns.md +++ b/docs/user/editor/patterns.md @@ -1,7 +1,5 @@ # Trip Patterns -## Terminology - ### Patterns Patterns refer to the recurring schedules and frequencies of transit trips. They can be thought of as a template for a particular route, indicating the days of the week and times of day that trips will be available, as well as the frequency of service during those periods. diff --git a/docs/user/editor/routes.md b/docs/user/editor/routes.md index 02de8bed8..0e1e16290 100644 --- a/docs/user/editor/routes.md +++ b/docs/user/editor/routes.md @@ -1,9 +1,5 @@ # Routes - -## Terminology - -### Routes -In GTFS, a route is a group of trips that follow the same sequence of stops, but may have different stop times. It's identified by a unique route_id and contains information such as the route name, type, and operating agency. For more information, view the [GTFS specification route reference](https://gtfs.org/schedule/reference/#routestxt) +In GTFS, a route is a group of trips that follow one or more patterns and operate throughout a service day. It is identified by a unique route_id and contains information such as the route name, type, and operating agency. For more information, view the [GTFS specification route reference](https://gtfs.org/schedule/reference/#routestxt) ## Editing/Creating Routes diff --git a/docs/user/editor/schedules.md b/docs/user/editor/schedules.md index 7a3c156d8..4d8bcaa49 100644 --- a/docs/user/editor/schedules.md +++ b/docs/user/editor/schedules.md @@ -4,8 +4,6 @@ The schedule editor allows for the creation of trips/frequencies for any combina ![calendar-tab](https://datatools-builds.s3.amazonaws.com/docs/schedules/calendar-tab.png) -## Terminology - ### Calendars Transit calendars in GTFS are used to define the days of the week on which transit services are available. See the [GTFS specification calendar reference](https://gtfs.org/schedule/reference/#calendartxt) for more information. @@ -40,7 +38,7 @@ To start editing a calendar, click on `+ Create first calendar` if this is the f
## Editing/Creating Exceptions -To start editing an exception, select any existing exception (if applicable) on the left pane. You will be able to edit properties such as exception name, customize the exception type, add calendars to add, remove or swap and the time range the exception is applied to. To make a new exception, click on `New exception` on the top left of the pane. +To start editing an exception, select any existing exception (if applicable) on the left pane. You will be able to edit properties such as exception name, customize the exception type, select calendars to add, remove or swap and the time range the exception is applied to. To make a new exception, click on `New exception` on the top left of the pane. ![new-exception](https://datatools-builds.s3.amazonaws.com/docs/schedules/new-exception.png) @@ -127,10 +125,12 @@ The following time formats are automatically recognized and converted: - 24-hr - `13:00:00` - `13:00` + - `1300` - 12-hr - - `1:00p` + - `1pm` - `1:00pm` - `1:00 pm` + - `1:00:00pm` - `1:00:00 pm` ### Tutorial Video: Editing/Creating Timetables diff --git a/docs/user/editor/stops.md b/docs/user/editor/stops.md index 0ade18fac..61794f023 100644 --- a/docs/user/editor/stops.md +++ b/docs/user/editor/stops.md @@ -20,10 +20,20 @@ To create a new stop, **right-click on the map** in the location you would like ### Editing a stop Once a stop is created or selected, the following parameters are required: -- **Name:** View the [GTFS reference](https://gtfs.org/schedule/best-practices/#stopstxt) for stop naming conventions -- **Location:** These are defined with latitude and longitude. **Note:** Stop locations should have an error of no more than four meters when compared to the actual stop position. +- **Stop ID (`stop_id`):** Identifies a stop, station, or station entrance. +- **Location (`stop_lat/stop_lon`):** These are defined by latitude and longitude. **Note:** Stop locations should have an error of no more than four meters when compared to the actual stop position. + +Optionally, additional parameters can be included such as: +- **Stop Code (`stop_code`):** A short code that uniquely identifies a stop for passengers. +- **Stop Name (`stop_name`):** The name of the location for a stop. +- **Stop Description (`stop_desc`):** A description providing additional information about the stop. +- **Zone ID (`zone_id`):** The fare zone for a stop. +- **Stop Timezone (`stop_timezone`):** Timezone of the stop. +- **Level ID (`level_id`):** Level of the location. +- **Platform Code (`platform_code`):** Code that identifies the platform for a stop. For stations with multiple platforms. +- **Parent Station (`parent_station`):** Defines the hierarchy of stops in `stops.txt`. +- **Wheelchair Boarding (`wheelchair_boarding`):** A value (0, 1, or 2) that identifies whether wheelchair boardings are possible at the stop. -Optionally, parameters like the zone ID, parent station or stop timezone can be defined. ### Moving a stop To move a selected stop, **click and drag the stop to the new location**. Or, if already you know the latitude and longitude coordinates, you can copy these into the text fields. After moving the stop, click save to keep the changes. diff --git a/docs/user/introduction.md b/docs/user/introduction.md index d15c22049..8c9373ce6 100644 --- a/docs/user/introduction.md +++ b/docs/user/introduction.md @@ -2,7 +2,7 @@ ## Conceptual Overview -The GTFS Data Manager makes the creation, updates, validation and deployment of GTFS data feeds easier. +The GTFS Data Manager enables exchange and coordination of data creation, updates, validation and deployment of GTFS data feeds for transit schedules. GTFS producers (transit operators, local governments, etc.) can share existing feeds or use the build function in GTFS Editor to create and maintain feeds. GTFS creators can use the built in validator to check for potential issues. diff --git a/docs/user/managing-projects-feeds.md b/docs/user/managing-projects-feeds.md index cef32515d..943c2170d 100644 --- a/docs/user/managing-projects-feeds.md +++ b/docs/user/managing-projects-feeds.md @@ -2,15 +2,13 @@ ## Creating Projects -Projects are created from the main Project listing page. Click the `Create Project` button to create a new Project; a row for the new Project will appear in the table. Type a name and click the check button (or hit Enter/Return) to finish creating the Project. +Projects are created from the main Project listing page. Click the `New Project` button to create a new Project; a row for the new Project will appear in the table. Type a name and click the check button (or hit Enter/Return) to finish creating the Project. ![create-project](https://datatools-builds.s3.amazonaws.com/docs/intro/create-project.png) ## Managing Projects -Clicking on a project in the main project listing will take you to the detailed project profile page. - -The **Settings** tab can be expanded to reveal optional properties that can be specified for the project. These include the location of the project's geographic coverage area (specified either as a single coordinate or a rectangular region) and the default time zone. These values, when provided, are used to populate the corresponding feed-level properties when creating new feeds within this project. +Clicking on a project in the main project listing will take you to the detailed project profile page: ![create-project](https://datatools-builds.s3.amazonaws.com/docs/intro/project-settings.png) ## Creating a Feed Source @@ -19,7 +17,7 @@ To the left of the Project Settings panel is the **Feed Sources** panel. Feed So ![create-project](https://datatools-builds.s3.amazonaws.com/docs/intro/project-feed-sources.png) -Feed Sources are created from a Project's main profile page. Click the `+New` button from the `Actions` dropdown to create a new feed; Specify a name and optional feed source URL and click "Save". You may also adjust whether to automatically fetch the feed from the source URL and to make the feed deployable. +Feed Sources are created from a Project's main profile page. Click the `+New` button from the `Actions` dropdown to create a new feed; Specify a name and optional feed source URL and click on `Save`. You may also adjust whether to automatically fetch the feed from the source URL and to make the feed deployable. ![create-project](https://datatools-builds.s3.amazonaws.com/docs/intro/create-feed-source.png) @@ -55,9 +53,9 @@ Feed Versions are created from the main Feed Source profile page. There are thre 3. **Import From the GTFS Editor**: Select `From snapshot` from the `+ Create new version` dropdown. The list of snapshots should now be visible showing any available snapshots of the feed in the Editor. Select the desired snapshot by clicking the "Publish" button to publish the snapshot as a new version. -4. **Service Period Merge** (certain Data Tools configurations only): If a Feed Source has two or more Feed Versions, a new Feed Version can be created by merging two versions representing a transit agency's service over different time periods. While viewing a particular Feed Version, click `Merge with version` (underneath the map view) to select which past version you would like to merge with. +4. **Service Period Merge** (certain Data Tools configurations only): If a Feed Source has two or more Feed Versions, a new Feed Version can be created by merging two versions representing a transit agency's service over different time periods. While viewing a particular Feed Version, click on `Merge with version` (underneath the map view) to select which past version you would like to merge with. -5. **Regional Merge**: For Projects that contain multiple Feed Sources across a region, it can be useful to merge multiple transit agencies together into a combined GTFS feed for the entire region. While viewing a Project's list of Feed Sources, click `Actions > Merge all` to produce a combined GTFS file for all Feed Sources. +5. **Regional Merge**: For Projects that contain multiple Feed Sources across a region, it can be useful to merge multiple transit agencies together into a combined GTFS feed for the entire region. While viewing a Project's list of Feed Sources, click on `Actions > Merge all` to produce a combined GTFS file for all Feed Sources. **Note**: when uploading or fetching a feed, and the file being uploaded or fetched is not different from the latest version, no new Feed Version will be created. @@ -75,7 +73,12 @@ Follow the steps below to configure Feed Transformations for an existing Feed So 1. Select a Feed Source and click on `Settings > Feed Transformations`. 2. From here, click on `Add transformation` to begin creating a new set of rules for incoming GTFS feeds. Your first ruleset will automatically apply to GTFS that is fetched automatically and manually uploaded, but this can be changed for each ruleset to apply to any of the retrieval methods listed in [Creating Feed Versions](#creating-feed-versions). -3. Click on `Add step to transformation` to select a transformation type and fill in the required fields for each type. Multiple transformations can be specified, and each will be applied to the incoming GTFS file in the order in which they are defined. +3. Click on `Add step to transformation` to select a transformation type and fill in the required fields for each type. Multiple transformations can be specified and each will be applied to the incoming GTFS file in the order in which they are defined. + +The types of feed transformations include: +- **Normalize field transformation:** Standardize or the values within the GTFS data. +- **Preserve custom fields transformation:** This transformation prevents custom, user-added fields in GTFS data from getting lost. +- **Add custom file transformation:** Include custom files in the GTFS data. ![create-project](https://datatools-builds.s3.amazonaws.com/docs/intro/configure-feed-transformations.png) @@ -89,7 +92,7 @@ A more in depth summary is available under the Transformation Results tab on the ## Viewing and Managing Feed Versions -The Feed Version navigator enables you to browse through all available versions of a given feed using the `←` and `→` buttons (or view a list of all versions). You can also use this interface to: +The Feed Version navigator allows you to browse through all available versions of a given feed using the `←` and `→` buttons (or view a list of all versions). You can also use this interface to: - Download a Feed Version to your local machine as a GTFS data file. - Load a version into the Editor. diff --git a/docs/user/managing-users.md b/docs/user/managing-users.md index 8f2534e12..235736d1b 100644 --- a/docs/user/managing-users.md +++ b/docs/user/managing-users.md @@ -4,7 +4,7 @@ User accounts in the Transit Data Tools suite are managed via Auth0, a third-party authentication service. (For details on setting up Auth0 for use with this application, please refer to the Deployment documentation.) -Auth0 provides access through internally defined user accounts and third-party identity providers (e.g., social networking sites); however, this documentation only addresses internal accounts. Internal accounts employ username-password authentication, with a user's email address serving as the unique username. +Auth0 allows for access via internally defined user accounts as well as third-party identity providers (e.g. social networking sites); however, this documentation only addresses internal accounts. Internal accounts employ username-password authentication, with a user's email address serving as the unique username. ## User Permissions @@ -18,7 +18,7 @@ Three types of administrator-level users exist: - **Project-level administrator**: holds full access to a single project, including all project-level permissions. Is not able to create new projects or administer users. ### Non-admin users -For non-administrative users, permissions may be assigned on an individual basis by choosing `Custom`. A non-administrative user's permissions can also be set to only apply to particular feeds within a project. By default, all users with project access have read-only permissions for all project feeds. +For non-administrative users, permissions may be assigned on an individual basis by choosing `Custom`. A non-administrative user's permissions can also be set to only apply to particular feeds within a project. By default, all users with project access have read-only access for all project feeds. #### User permissions examples 1. A user may need edit privileges to only one feed source. In this case, the `Edit GTFS feeds` and the specific feed (e.g., Agency X) would be checked. diff --git a/mkdocs.yml b/mkdocs.yml index 2c0161f2c..1922914d5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,11 +13,11 @@ nav: - 'Managing Projects & Feeds': 'user/managing-projects-feeds.md' - 'Managing Users': 'user/managing-users.md' - 'GTFS Editor': - - Introduction: 'user/editor/introduction.md' + - Getting Started: 'user/editor/getting-started.md' - Stops: 'user/editor/stops.md' - Routes: 'user/editor/routes.md' - Patterns: 'user/editor/patterns.md' - - Schedules/Calendars: 'user/editor/schedules.md' + - Schedules: 'user/editor/schedules.md' - Fares: 'user/editor/fares.md' - Deploying to OTP: - Overview: user/otp-deployment.md