diff --git a/.travis.yml b/.travis.yml index 84c6f8a50..7e10c1303 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,11 +7,13 @@ cache: yarn: true before_install: - npm i -g codecov + - pip install --user mkdocs script: - yarn run lint - yarn run cover-client - codecov - yarn run build + - mkdocs build # If sudo is disabled, CI runs on container based infrastructure (allows caching &c.) sudo: false diff --git a/docs/dev/deployment.md b/docs/dev/deployment.md index 59d3e6f72..fd143df5b 100644 --- a/docs/dev/deployment.md +++ b/docs/dev/deployment.md @@ -95,7 +95,7 @@ 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. -![Auth0 token generator](/img/auth0-token-generator.png =50x) +![Auth0 token generator](../img/auth0-token-generator.png) To allow for the creation, deletion and editing of users you must generate a token for the following scopes: diff --git a/docs/img/add-fare-zone.png b/docs/img/add-fare-zone.png new file mode 100644 index 000000000..c1ea0fec8 Binary files /dev/null and b/docs/img/add-fare-zone.png differ diff --git a/docs/img/auth0-token-generator.png b/docs/img/auth0-token-generator.png index 5707622a8..0acae707e 100644 Binary files a/docs/img/auth0-token-generator.png and b/docs/img/auth0-token-generator.png differ diff --git a/docs/img/create-project.png b/docs/img/create-project.png index f919a4802..14fa539a5 100644 Binary files a/docs/img/create-project.png and b/docs/img/create-project.png differ diff --git a/docs/img/create-user.png b/docs/img/create-user.png index 9e418de78..3c5ba5b9e 100644 Binary files a/docs/img/create-user.png and b/docs/img/create-user.png differ diff --git a/docs/img/edit-calendars.png b/docs/img/edit-calendars.png new file mode 100644 index 000000000..b8f6b5618 Binary files /dev/null and b/docs/img/edit-calendars.png differ diff --git a/docs/img/edit-fare-rules.png b/docs/img/edit-fare-rules.png new file mode 100644 index 000000000..2aaf49bd1 Binary files /dev/null and b/docs/img/edit-fare-rules.png differ diff --git a/docs/img/edit-fares.png b/docs/img/edit-fares.png new file mode 100644 index 000000000..1c199c0af Binary files /dev/null and b/docs/img/edit-fares.png differ diff --git a/docs/img/edit-frequencies.png b/docs/img/edit-frequencies.png new file mode 100644 index 000000000..24ce9934e Binary files /dev/null and b/docs/img/edit-frequencies.png differ diff --git a/docs/img/edit-patterns.png b/docs/img/edit-patterns.png new file mode 100644 index 000000000..e79de51c0 Binary files /dev/null and b/docs/img/edit-patterns.png differ diff --git a/docs/img/edit-routes.png b/docs/img/edit-routes.png new file mode 100644 index 000000000..ac8f62010 Binary files /dev/null and b/docs/img/edit-routes.png differ diff --git a/docs/img/edit-stops.png b/docs/img/edit-stops.png new file mode 100644 index 000000000..126e3f755 Binary files /dev/null and b/docs/img/edit-stops.png differ diff --git a/docs/img/edit-timetables.png b/docs/img/edit-timetables.png new file mode 100644 index 000000000..ad490ba50 Binary files /dev/null and b/docs/img/edit-timetables.png differ diff --git a/docs/img/feed-profile.png b/docs/img/feed-profile.png index 3f89ed128..1e76f459c 100644 Binary files a/docs/img/feed-profile.png and b/docs/img/feed-profile.png differ diff --git a/docs/img/feed-version-navigator.png b/docs/img/feed-version-navigator.png index 057ce3632..59f6b491b 100644 Binary files a/docs/img/feed-version-navigator.png and b/docs/img/feed-version-navigator.png differ diff --git a/docs/img/pattern-add-stop.png b/docs/img/pattern-add-stop.png new file mode 100644 index 000000000..c2538afba Binary files /dev/null and b/docs/img/pattern-add-stop.png differ diff --git a/docs/img/pattern-insert-stop.png b/docs/img/pattern-insert-stop.png new file mode 100644 index 000000000..7cee6c17f Binary files /dev/null and b/docs/img/pattern-insert-stop.png differ diff --git a/docs/img/pattern-shape-panel.png b/docs/img/pattern-shape-panel.png new file mode 100644 index 000000000..ef58884e3 Binary files /dev/null and b/docs/img/pattern-shape-panel.png differ diff --git a/docs/img/pattern-stop-order.png b/docs/img/pattern-stop-order.png new file mode 100644 index 000000000..8b77afef2 Binary files /dev/null and b/docs/img/pattern-stop-order.png differ diff --git a/docs/img/pattern-stop-toolbar.png b/docs/img/pattern-stop-toolbar.png new file mode 100644 index 000000000..98633237d Binary files /dev/null and b/docs/img/pattern-stop-toolbar.png differ diff --git a/docs/img/project-profile.png b/docs/img/project-profile.png index 2e134d87d..7a0d19bf0 100644 Binary files a/docs/img/project-profile.png and b/docs/img/project-profile.png differ diff --git a/docs/img/public-portal.png b/docs/img/public-portal.png index c2abe5f0f..4b7654a88 100644 Binary files a/docs/img/public-portal.png and b/docs/img/public-portal.png differ diff --git a/docs/img/quick-access-toolbar.png b/docs/img/quick-access-toolbar.png new file mode 100644 index 000000000..aa0c807a7 Binary files /dev/null and b/docs/img/quick-access-toolbar.png differ diff --git a/docs/img/schedule-exception.png b/docs/img/schedule-exception.png new file mode 100644 index 000000000..25e2d4406 Binary files /dev/null and b/docs/img/schedule-exception.png differ diff --git a/docs/img/schedule-toolbar.png b/docs/img/schedule-toolbar.png new file mode 100644 index 000000000..17bf270d1 Binary files /dev/null and b/docs/img/schedule-toolbar.png differ diff --git a/docs/img/select-trips.png b/docs/img/select-trips.png new file mode 100644 index 000000000..ccd485a64 Binary files /dev/null and b/docs/img/select-trips.png differ diff --git a/docs/img/timetable-selector.png b/docs/img/timetable-selector.png new file mode 100644 index 000000000..1b117aad6 Binary files /dev/null and b/docs/img/timetable-selector.png differ diff --git a/docs/img/user-admin.png b/docs/img/user-admin.png index 7e15856d9..a42b4d52e 100644 Binary files a/docs/img/user-admin.png and b/docs/img/user-admin.png differ diff --git a/docs/img/user-profile.png b/docs/img/user-profile.png index a23d590ad..6b17919eb 100644 Binary files a/docs/img/user-profile.png and b/docs/img/user-profile.png differ diff --git a/docs/img/view-all-stops.png b/docs/img/view-all-stops.png new file mode 100644 index 000000000..c1641d5e9 Binary files /dev/null and b/docs/img/view-all-stops.png differ diff --git a/docs/style.css b/docs/style.css index 6c3a8e355..c7cda3d80 100644 --- a/docs/style.css +++ b/docs/style.css @@ -1 +1,12 @@ img[alt=screenshot] { width: 100%; } + +/*Ignore first heading in page in TOC list*/ +li.toctree-l3:first-child { + display: none; +} + +.img-center { + width: 300px; + margin-left: auto; + margin-right: auto; +} diff --git a/docs/user/editor/calendars.md b/docs/user/editor/calendars.md new file mode 100644 index 000000000..6800bb192 --- /dev/null +++ b/docs/user/editor/calendars.md @@ -0,0 +1,43 @@ +# Calendars + +## Editing calendars + +To begin editing calendars, click the 📅 button on the lefthand navigation bar. + +![screenshot](../../img/edit-calendars.png) + +Choose a calendar from the list to begin editing. To create a new calendar, click `+ New calendar`. **Note:** as with all newly created items (except patterns), the new calendar will not be saved until the save icon (💾) is clicked. + +## Calendar details + +- **Service ID** - unique ID for the calendar +- **Description** - optional description for calendar (defaults to initial days of week specified) +- **Days of service** - days of week on which the service operates +- **Start/End dates** - the first and last day of that service assigned to the calendar should run + +## Editing schedule exceptions + +Schedule exceptions allow users to define days where special services should replace the regularly operating calendars. To create a schedule exception, click the `Exceptions` tab and then click `+ New exception` (replaces the "New calendar" button). +
+ ![schedule exception](../../img/schedule-exception.png) +
+ +## Exception details + +- **Name** - name of schedule exception +- **Schedule to run** - the chosen schedule that should replace the regularly operating calendars (see below Exception types) +- **Dates** - one or more dates to which the schedule exception applies + +## Exception types + +There are a number of built-in exception types (or available schedules to run) that allow for a high degree of flexibility when assigning special services. + +- **[Su, M, Tu, W, Th, F, Sa]** - replaces all service for the specified dates with the calendar(s) that operate on the chosen day of the week +- **No service** - indicates that no service of any kind should operated on the specified dates +- **Custom** - replace all service for the specified dates with trips operating on the one or more calendars specified with this option. E.g., run only `holiday` and `holiday-plus` calendar on Thanksgiving Day. +- **Swap** - similar to the **Custom** option, however this option allows for removing one or more specific calendars for the specified dates and/or adding one or more specific calendars. This option is especially useful if only certain routes have altered service on specific dates. For example, a user could remove the `weekday-route-1` calendar and add the `special-route-1` calendar. + +## Editing schedules +Click `Edit schedules` to begin creating or editing trips/frequencies for a trip pattern. You will be redirected to the Schedule Editor. For more information on creating schedules for a pattern, see [Trips](schedules). + +**Note**: At least one route, pattern and calendar must have been created to edit schedules. diff --git a/docs/user/editor/fares.md b/docs/user/editor/fares.md new file mode 100644 index 000000000..a2bc1e8c2 --- /dev/null +++ b/docs/user/editor/fares.md @@ -0,0 +1,35 @@ +# Fares + +## Editing fares + +To begin editing fares, click the fare ticket button on the lefthand navigation bar. + +![screenshot](../../img/edit-fares.png) + +Choose a fare from the list to begin editing. To create a new fare, click `+ New fare`. **Note:** as with all newly created items (except patterns), the new fare will not be saved until the save icon (💾) is clicked. + +## Fare attributes + +Fare attributes describe the basic information about a fare. Full details on fare attributes can be found at the [GTFS specification reference](https://developers.google.com/transit/gtfs/reference/fare_attributes-file). + +## Fare rules + +To edit fare rules, you must first create and save a fare with attributes. After choosing a fare, click the `Fare rules` tab and define one or more rules for this fare using the following types: + +1. **Route** - applies to any itinerary that includes the route +2. **From/to zone** - applies to any itinerary that travels from the origin zone to the destination zone +3. **Contains zone** - applies to any itinerary that passes through *each* `contains` zone + +**Note:** fare rules can be tricky, see the [GTFS specification reference](https://developers.google.com/transit/gtfs/reference/fare_rules-file) for more information on how fare rules apply. +
+ ![screenshot](../../img/edit-fare-rules.png) +
+ +## Creating fare zones + +To create a fare zone for use in fare rules, you must first select a stop that you would like to include in the zone. Click in the `zone_id` dropdown and begin typing the new `zone_id`. Click `Create new zone: [zone_id]` and then save the stop. Repeat for as many zones as needed. +
+ ![screenshot](../../img/add-fare-zone.png) +
+ +Once created and assigned to one or more stop, fare zones can be used when defining fare rules for **From/to zone** or **Contains zone**. diff --git a/docs/user/editor/introduction.md b/docs/user/editor/introduction.md new file mode 100644 index 000000000..ee000ef2e --- /dev/null +++ b/docs/user/editor/introduction.md @@ -0,0 +1,46 @@ +# Introduction + +## Getting started + +The GTFS Editor (or Editor) allows users to edit GTFS feeds imported from the Data Manager (see [Loading Feed Versions into Editor](../../user/managing-projects-feeds/#loading-feed-versions-into-editor)) or create GTFS completely from scratch. + +Once you begin editing a feed, + +## Saving in the Editor + +When editing routes, stop, calendars, and any other entities in the Editor, you must manually save any changes using the save icon (💾) button to avoid accidental changes. The only exception here is for patterns, which save your changes automatically. + +## Navigating the Editor + +The primary tables in GTFS (feed info, routes, stops, calendars, and fares) all correspond to items in the lefthand navigation bar, which allow you to create, edit, or delete records for each of these tables. + +Some tables are nested underneath these primary tables. Here's how to find them and what they're called in the Editor: + +- **[Routes](routes)** + - **[Trip patterns](patterns)** (shapes and stop times) - allows users to create one or more stop sequences for a given route. For example, a route may have an inbound and outbound trip pattern. + - **[Schedules](schedules)** (trips and frequencies) - define the trips for a trip pattern. Depending on whether the pattern is timetable- or frequency-based, these will be defined as individual trips or frequency intervals. +- **[Calendars](calendars)** + - **[Exceptions](calendars/#editing-schedule-exceptions)** (i.e., calendar dates) +- **[Fares](fares)** (fare attributes) + - **[Fare rules](fares/#fare-rules)** + +## Quick access toolbar + +In the bottom, righthand corner of the Editor, you'll find the quick access toolbar that has a few convenient features you might need while editing. +
+![quick access toolbar](../../img/quick-access-toolbar.png) +
+ +From left to right, these functions are: + +- Hide the quick access toolbar +- Navigate back to feed source or project in Data Manager +- Upload a zipped routes shapefile to display polylines as a visual aid for drawing trip patterns +- Create any entity (route, stop, calendar, etc.) +- Take snapshot (save point) for current state of data (or revert to previous snapshot) + +## GTFS tables/fields supported + +For a technical look at which fields are supported by the Editor, check out this [data file](https://github.com/conveyal/datatools-ui/blob/master/gtfs.yml) which contains a full listing of all of the supported tables and fields in the application. + +Are there fields missing that you need? Feel free to contact us at contact@conveyal.com to see how we might be able to help. diff --git a/docs/user/editor/patterns.md b/docs/user/editor/patterns.md new file mode 100644 index 000000000..db44ac76d --- /dev/null +++ b/docs/user/editor/patterns.md @@ -0,0 +1,133 @@ +# Trip Patterns + +## Editing trip patterns + +To begin editing trip patterns (or patterns), first select or create a route. Click the `Trip patterns` tab. + +![screenshot](../../img/edit-patterns.png) + +Choose a pattern from the list to begin editing. To create a new pattern, click `+ New pattern`. + +## Pattern toolbar + +### Zoom to pattern extents +Clicking the 🔍 button (in the top toolbar) with a pattern selected adjusts the map view to show the entire pattern you are editing. + +### Duplicate pattern +Creates a duplicate of the active pattern (duplicated pattern name becomes `[Pattern name] copy`) if you need to create a similar, but different trip pattern. + +### Reverse pattern +To reverse the sequence of stops for a pattern, click the yellow opposing arrows button. **Note**: this is a destructive action and should usually only be used with Duplicate Pattern. + +### Delete pattern + +Deletes the active pattern. **Note**: deleted patterns cannot be recovered. + +## Pattern details + +- **Name** – the name of the trip pattern within the route, for example a service that runs the full length of the route or a service that only runs part of the length of the route. + + +- **Use timetables/frequencies** - whether the pattern uses timetables, i.e., individual entries for each trip made over the course of a day, or frequencies, which define varying frequencies (or headways) according to time intervals over the course of a day. +- **Direction** - corresponds to the `direction_id` field in GTFS. All trips associated with this pattern will be assigned the direction provided here. + +## Editing schedules +Click `Edit schedules` to begin creating or editing trips/frequencies for a trip pattern. You will be redirected to the Schedule Editor. For more information on creating schedules for a pattern, see [Trips](schedules). + +## Stop sequence +### Adding stops +To begin constructing a pattern, click `+ Add stop`. You can then search for stops to add by name in the dropdown that appears or zoom into the map and add stops by clicking on them and clicking `+ Add stop`. +
+![add stop from dropdown](../../img/pattern-add-stop.png) +
+ +As you add stops, the pattern shape will update according to the street network. Keep selecting and adding stops in the sequence the route passes through them until the route is complete. + +### Inserting stops mid-sequence +If you realize you have missed a stop from the sequence it can be added in after the fact. When adding via the dropdown, stops can only be added to the end of the sequence; however, if you're adding via the map, you can choose where exactly to insert the stop. +
+![insert stop from map](../../img/pattern-insert-stop.png) +
+ +### Pattern stop toolbar +The pattern stop toolbar can be found by clicking the pattern stop in the map view. +
+![pattern stop toolbar](../../img/pattern-stop-toolbar.png) +
+ +- **Save** - saves any edits to the travel and dwell times. +- **Edit** - allows user to begin editing the stop's details (clicking the browser **Back** button will bring you back to editing the pattern). **Note**: be sure you have saved any pattern information before jumping to edit a stop. +- **Remove** - removes the stop from the pattern. +- **Add** - add the stop to the sequence at an additional location. This is useful for patterns that might visit the same stop more than once (e.g., loop routes). + +### Changing the order of stops +If a stop is in the wrong order, you can click and drag the stop from the list view into the correct sequence. The sequence displayed on the stop being dragged will only update after being dropped into place. +
+![drag and drop pattern stop](../../img/pattern-stop-order.png) +
+ +**Note**: if inserting stops mid-sequence or changing the order of stops, the pattern shape will not update automatically. You must edit the pattern manually or click the `Create` button to regenerate the pattern shape from the stops. + +### Removing stops +Stops can be removed from the pattern by clicking the red 🗑 button found in the expanded stop card or by clicking the pattern stop on the map view. + + +## Stop timings +### Calculate timings +The average speed for the route can be used to calculate all the time gaps between stops in one go. Once the stops have been added and the pattern alignment is drawn simply click **Calc. Times** and the time between stops will automatically fill in. + +- **Average speed** - average speed (in km/hr) to use when calculating timings +- **Dwell time** – allows you to assign the same dwell time to all stops within a trip + pattern + +### Manual timings +Individual timings for each pattern stop can also be assigned either through expanded the stop card in the list of stops or via clicking the pattern stop on the map view. + +- Travel time – the time it took to get from the previous station (should be 00:00 on the first stop of the sequence) +- Dwell time – the time the vehicle rests at the stop + + + + +## Creating pattern alignments +As mentioned above, pattern shapes will begin to draw automatically as stops are added in sequence. However, if you need to make adjustments to the auto-generated shape, clicking `Edit` will allow you to begin editing the shape segments between stops. + +### Basic editing +Once editing a pattern shape, there are a few behaviors you should be aware of: + +- Dragging a handle (✕) will create a new alignment between stops or surrounding handles +- Clicking the pattern will add additional handles to the segment +- Clicking added handles will remove them (**Note**: only grey handles can be removed) + +### Shape toolbar +#### Before editing +- **Edit** - begin editing the pattern shape +- **Delete** - delete the pattern shape +- **Create** - creates alignment that follows streets from pattern stops + +#### While editing +- **Save** - Save changes to pattern shape and leave editing mode. +- **Undo** - Undo last change. +- **Cancel** - Cancel edits and leave editing mode. + +### Edit settings +- **Snap to streets** - snaps segments between handles and stops to streets. If unchecked, segments will form straight lines between handles and stops (e.g., for drawing shapes for rail lines). +- **Snap to stops** - keeps shape segments snapped to stops. If unchecked, stop handles will become draggable. In most cases, this setting should remain checked. +- **Show stops** - toggles whether stops are visible because sometimes stop markers can get in the way when trying to draw shapes. +
+![pattern shape editing options](../../img/pattern-shape-panel.png) +
+ +### Editing modes + +There are a few different editing modes that allow for the quick and easy creation of pattern shapes: + +- **Drag handles** (default) - drag handles to change the pattern segment between stops. This mode is also in effect during the advanced modes listed below. +- **Add stop at click** - at each click on the map, a new stop is generated and the pattern is extended to this stop. +- **Add stop at interval** - at each click on the map, stops are generated along the auto-generated pattern extended to the map click at the user-defined spacing interval from 100 to 2000 meters. +- **Add stop at intersection** (experimental, not available in all regions) - at each click on the map, stops are generated along the auto-generated pattern extended to the map click according to the user-defined parameters: + - **Offset from intersection** - distance the stop should be placed from the intersection + - **Before/after** - whether stop should be placed before or after intersection + - **Every *n* intersections** - the number of intersections at which each new stop should be placed + +**Note**: the last three advanced editing modes should only be used when creating routes in new areas where stops don't already exist. diff --git a/docs/user/editor/routes.md b/docs/user/editor/routes.md new file mode 100644 index 000000000..d3a0a504d --- /dev/null +++ b/docs/user/editor/routes.md @@ -0,0 +1,51 @@ +# Routes + +## Editing routes + +To begin editing routes, click the 🚍 button on the lefthand navigation bar. + +![screenshot](../../img/edit-routes.png) + +Choose a route from the list or search by route name in the dropdown. To create a new route, click `+ New route`. **Note:** as with all newly created items (except patterns), the new route will not be saved until the save icon (💾) is clicked. + +## Zoom to route extents +Clicking the 🔍 button (in the top toolbar) with a route selected adjusts the map view to show the entire route (i.e., all patterns) you are editing. + +## Route details + +Some of the fields to be filled in are required before you can ‘Save and Continue’ and move to the next step, these are: + +- **Short name** – name of the service/route, this may just be a number +- **Long name** – the full name of the route, often including the origin and destination +- **Route Type** – the type of vehicle/transport used on the route +Other fields in this section are optional and do not have to be filled in, these are: +- **Description** – a description of the route, do not simply repeat the information in ‘Long name’ +- **URL** – a link to a webpage with information on the specific route, such as the timetable +- **Color** – if a route has a color (for use in trip planners etc) it can be assigned here +- **Text color** – if a route has a text color (for use in trip planners etc) it can be assigned here +- **Comments** – any additional information about the route can be placed here + +Once all the required fields, and any of the desired optional fields, are filled in click ‘Save and continue’. + + +## Review + +This final page allows you to show if a route has been completely entered, and if it has whether it has been checked and approved for inclusion in the GTFS feed. + +### Status + +There are three options for **Status**: + +- **In-Progress** - showing a route has not been completely entered. +- **Pending Approval** - a route has all the information entered and is awaiting a senior person to sign it off +- **Approved** - all the above stages have been completed. + +### Publicly visible + +Leave this box unchecked if you are entering a route that is not to be included in a GTFS output, or is in-progress. + +## Trip Patterns + +Once you've created and saved a route, you can then begin creating trip patterns for the route. + +[Learn about editing trip patterns »](patterns) diff --git a/docs/user/editor/schedules.md b/docs/user/editor/schedules.md new file mode 100644 index 000000000..ee99b9e7b --- /dev/null +++ b/docs/user/editor/schedules.md @@ -0,0 +1,69 @@ +# Trips + +## Selecting schedules +The schedule editor allows users to create trips/frequencies for any route, pattern, and calendar combination. The selectors at the top of the page allow users to navigate between calendars for a given pattern or switch between patterns for a route or even routes within the feed. + +Each selection has a set of statistics associated with it to give you a sense of how it fits in with the feed: + +- **Route** + - \# of trips for the entire route +- **Pattern** + - \# of trips for pattern + - \# of calendars containing these trips. +- **Calendar** + - \# of trips for selected pattern / \# of trips for entire route + - \# of routes with trips in calendar + - \# of trips in calendar for entire feed + +![schedule selector](../../img/timetable-selector.png) + +## Schedule toolbar +
+ ![schedule toolbar](../../img/schedule-toolbar.png) +
+ +- **Add trip** - add blank trip (first timepoint is `00:00:00`) +- **Duplicate trip(s)** - duplicate the last trip in the spreadsheet or whichever rows are selected +- **Delete trip(s)** - delete selected rows +- **Undo all** - undo all changes +- **Save** - save all changes +- **Offset trip(s)** - specify an offset (`HH:MM`) to offset the last trip in the spreadsheet or whichever rows are selected + +## Selecting trips +To select trips to offset, duplicate or delete, click the row number on the lefthand side of the row. To toggle selection of all trips, click the box in the upper lefthand corner. +
+ ![select trips](../../img/select-trips.png) +
+ +## Recognized time entry formats +When entering times manually into the schedule editor they will automatically be converted to a standardized format `13:00:00`. The following time formats are automatically recognized and converted: + +- 24-hr + - `13:00:00` + - `13:00` +- 12-hr + - `1:00p` + - `1:00pm` + - `1:00 pm` + - `1:00:00 pm` + +## Editing timetables +Trip details include: + +- **Block ID** - identifies the vehicle used for the trip +- **Trip ID** - unique identifier for the trip +- **Trip Headsign** - headsign for the trip +- **Arrival/Departure Times** - arrival and departure times (departures shown in grey text) for each stop along the pattern + +![editing timetables](../../img/edit-timetables.png) + +## Editing frequencies +Frequency details include: + +- **Block ID** - identifies the vehicle used for the trip +- **Trip ID** - unique identifier for the trip +- **Trip Headsign** - headsign for the trip +- **Start/End Times** - define the beginning and end time for the interval over which the frequency operates +- **Headway** - headway (in minutes) that the pattern runs during the time interval + +![editing frequencies](../../img/edit-frequencies.png) diff --git a/docs/user/editor/stops.md b/docs/user/editor/stops.md new file mode 100644 index 000000000..054b9ee36 --- /dev/null +++ b/docs/user/editor/stops.md @@ -0,0 +1,39 @@ +# Stops + +## Editing stops + +To begin editing stops, click the map marker icon button on the lefthand navigation bar. + +![screenshot](../../img/edit-stops.png) + +## Selecting a stop + +Choose a stop from the list or search by stop name in the dropdown. + +You can also **zoom into the map** while the stop list is visible and once you're close enough you'll begin to see stops displayed. Click one to begin editing its details. + +## Creating a stop: right-click on map + +To create a new stop, **right-click on the map** in the location you would like to place the stop. **Note:** as with all newly created items (except patterns), the new stop will not be saved until the save icon (💾) is clicked. + +## Moving a stop + +To move a selected stop simply **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. + + + +## View all stops for feed + +To view all stops for a feed, hover over the map layers icon (in the top, lefthand corner of the map) and turn on the `Stop locations` layer. When you do, you'll see all of the stops (which appear as grey circles) for the feed even at wide zoom levels. This layer can be viewed whether or not the stop list is visible, so it can be helpful for users who would like to view stop locations alongside routes or trip patterns. + +![screenshot](../../img/view-all-stops.png) + +Clicking on a stop shown in this layer will select the stop for editing, but be careful—it can be tricky to select the right stop from very far away! + + + diff --git a/docs/user/introduction.md b/docs/user/introduction.md index 6341abc62..b630207c0 100644 --- a/docs/user/introduction.md +++ b/docs/user/introduction.md @@ -14,7 +14,7 @@ Projects are collections of feed sources and deployments. ### Feed Sources -Feed sources define the locations or upstream sources of GTFS feeds. These can be: +Feed sources define the locations or upstream sources of GTFS feeds. These can be any combination of: 1. **Manually Uploaded** - Manually collected/managed feeds provided directly by an external source. 2. **Fetched Automatically** - Public available feeds that can be fetch from a URL @@ -22,10 +22,10 @@ Feed sources define the locations or upstream sources of GTFS feeds. These can b ### Feed Versions -Feed Versions store specific instances of a GTFS feed for a given feed source as published over time. Each Feed Version has an associated GTFS file that is stored within the Data Manager, can be downloaded by users, and for which detailed information such as validation results is available. +Feed Versions store specific instances of a GTFS feed for a given feed source as published over time. Each Feed Version has an associated GTFS file that is stored within the Data Manager, can be downloaded by users, and for which detailed information such as validation results is available. ### Snapshots -Internally managed GTFS data sets are pulled from the GTFS Editor using “snapshots” defined in the editor interface. These snapshots are static versions of the data set that can be exported, or used as starting point for future edits. The Data manager only imports snapshotted versions of feeds. This allows users to ensure the correct version of data is being imported and to retrieve and review data in the future. +Internally managed GTFS data sets are pulled from the GTFS Editor using “snapshots” created in the editor interface. These snapshots are static versions of the data set, or save points, that can be exported, or used as starting point for future edits. The Data manager only imports snapshotted versions of feeds. This allows users to ensure the correct version of data is being imported and to retrieve and review data in the future. *Note: See section 2.6 in GTFS Editor User Manual for more information on snapshots.* diff --git a/docs/user/managing-projects-feeds.md b/docs/user/managing-projects-feeds.md index ceb1fd3c6..b98d48421 100644 --- a/docs/user/managing-projects-feeds.md +++ b/docs/user/managing-projects-feeds.md @@ -22,32 +22,50 @@ Feed Sources are created from a Project's main profile page. Click the "New Feed ## Managing Feed Sources -After a Feed Source has been created, it will appear in the Project's table of Feed Sources. From this table, the **name** of the Feed Source can be changed, the **public visibility** of the feed can be toggled, and basic summary information for the feed is presented. Users with sufficient permissions can also **delete** a Feed Source using the "X" button to the far right of its table listing. +After a Feed Source has been created, it will appear in the Project's table of Feed Sources. From this table, a basic summary of information for the feed is presented (including if the latest version has expired and how many validation issues it has). -To access all other settings for this Feed Source, click on the its name to access the full Feed Source profile page: +To access all settings for this Feed Source, click on the its name to access the full Feed Source profile page: ![screenshot](../img/feed-profile.png) -At the top of the page is the **Feed Source Settings** panel, which allows editing of basic Feed Source properties such as name and public visibility, and is also used to manage the retrieval of GTFS data (covered in more detail below). Any settings provided by custom extensions are also listed in this section. +At the top of the page is a set of tabs, which include: -Below the Settings panel is **Comments** panel, where users can leave and view comments specific to this Feed Source, and the **Feed Version Navigator**, which is used to view individual Feed Versions and is covered in more detail below. +- **GTFS** - main point of entry for Feed Source + - Feed Version Navigator (covered in more detail below) + - Feed Version Summary - view feed info and discover information about routes, patterns and stops + - Validation issues - view and filter list of validation issues + - Version comments - leave and view comments specific to a Feed Version +- **Snapshots** - list of Editor snapshots (or save points) +- **Comments** - where users can leave and view comments specific to this Feed Source +- **Settings** - access to Feed Source settings + - Editing basic Feed Source properties such as name, fetch URL, and public visibility + - Viewing/editing settings provided by custom extensions + - Deleting a Feed Source (for users with sufficient permissions) in the **Danger zone** properties. ## Creating Feed Versions Feed Versions are created from the main Feed Source profile page. There are three methods for creating new versions: -1. **Manually Upload a File**: Select "Manually Uploaded" from the "Retrieval Method" dropdown. The button next the the dropdown should now say "Upload." Click the "Upload" button to select a GTFS file from your local machine. +1. **Manually Upload a File**: Select "Manually Uploaded" from the `+ Create new version` dropdown. The button next the the dropdown should now say "Upload." Click the "Upload" button to select a GTFS file from your local machine. -2. **Fetch From A Remote URL**: Select "Fetched Automatically" from the "Retrieval Method" dropdown. A "Retrieval URL" field should now be visible. Enter the URL of remote feed into the field and click the "Update" button to fetch the file currently available from the specified URL. +2. **Fetch From A Remote URL**: Select "Fetch" from the `+ Create new version` dropdown. **Note:** to fetch a new version, the "Feed source fetch URL" property must be set to a valid GTFS URL under `Feed Source > Settings`. + +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. + +**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. + +## Loading Feed Versions into Editor -3. **Import From the GTFS Editor**: Select "Produced In-house" from the "Retrieval Method" dropdown. A "Snapshot" dropdown selector should now be visible showing any available snapshots of the feed in the GTFS Editor. Select the desired snapshot and click the "Update" button to import the feed. -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. ## Viewing and Managing Feed Versions -The Feed Version navigator allows you to navigate through all available versions of a given feed using the "Next" and "Previous" buttons. You may also use this interface to download a Feed Version to your local machine as a GTFS data file and delete a Feed Version from the Data Manager. (Note: deleting a Feed Version cannot be undone.) +The Feed Version navigator allows you to navigate 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, and +- delete a Feed Version from the Data Manager. (Note: deleting a Feed Version cannot be undone.) ![screenshot](../img/feed-version-navigator.png) -Below the navigator is information specific to the currently active version. This including basic feed statistics, the detailed feed validation report, and any user comments specific to this feed. +To the left of the navigator is a list of views available for to the currently active version. These include basic feed statistics, the detailed feed validation report, and any user comments specific to this feed. diff --git a/docs/user/managing-users.md b/docs/user/managing-users.md index 6c87b8b18..5363e12b7 100644 --- a/docs/user/managing-users.md +++ b/docs/user/managing-users.md @@ -11,21 +11,22 @@ Auth0 allows for access via internally defined user accounts as well as third-pa The Data Tools suite uses a system of user permissions to regulate access to various functions within the application. Two types of administrator-level users exist: - **Application-level administrator**: has full access to the Data Tools suite, including access to all projects and feed sources, the ability to create new projects, and the ability to create and manage users. +- **Organization-level administrator**: has full access to all projects and feed sources for an organization. **Note:** this user type is only for users of non-enterprise implementations (i.e., https://gtfs.conveyal.com). - **Project-level administrator**: has full access to a single project, including all project-level permissions. Is not able to create new projects or administer users. For non-administrative users, permissions may be assigned on an individual basis. A non-administrative user's permissions can also be set to only apply to particular feeds within a project (note that all users have read-only access to all feeds by default). ## Managing Users -To create or manage users, you must be logged in as and application-level administrator. Click the "User" tab at the top navigation bar to access the user management console. You will then see a list of all users in the system: +To create or manage users, you must be logged in as an application- or organization-level administrator. From the `Home` page, click the `Admin` button in the top right-hand box to access the user management console. You will then see a list of all users in the system: -![screenshot](../img/user-admin.png) +![screenshot](../img/user-admin.png?) -Click a user name to see an expanded user profile where specific permissions can be set: +Click `Edit` next to a user name to see an expanded user profile where specific permissions can be set: ![screenshot](../img/user-profile.png) -To create a new user, click the "Create User" button: +To create a new user, click the `Create User` button: ![screenshot](../img/create-user.png) diff --git a/docs/mkdocs.yml b/mkdocs.yml similarity index 56% rename from docs/mkdocs.yml rename to mkdocs.yml index 118cc482c..69110a321 100644 --- a/docs/mkdocs.yml +++ b/mkdocs.yml @@ -1,18 +1,27 @@ site_name: Transit Data Tools Docs site_url: http://conveyal-data-tools.readthedocs.io repo_url: https://github.com/conveyal/datatools-manager -docs_dir: ../docs -site_dir: ../target/mkdocs +docs_dir: docs +site_dir: target/mkdocs theme: readthedocs extra_css: [style.css] pages: - Home: 'index.md' - User Guide: - - 'Indroduction': 'user/introduction.md' + - Data Manager: + - 'Introduction': 'user/introduction.md' - 'Managing Projects & Feeds': 'user/managing-projects-feeds.md' - 'Managing Users': 'user/managing-users.md' - 'Appendix: GTFS Validation Warnings': 'user/appendix-gtfs-warnings.md' + - 'GTFS Editor': + - Introduction: 'user/editor/introduction.md' + - Routes: 'user/editor/routes.md' + - Patterns: 'user/editor/patterns.md' + - Stops: 'user/editor/stops.md' + - Schedules: 'user/editor/schedules.md' + - Calendars: 'user/editor/calendars.md' + - Fares: 'user/editor/fares.md' - Development Guide: - 'Deployment': 'dev/deployment.md' - 'Development': 'dev/development.md'