Merge pull request #48 from conveyal/user-doc-update

docs(docs): Update docs for new manager UI and editor module
ibi-group · Mar 6, 2017 · dedf2e1 · dedf2e1
2 parents 48f255b + 820a90f
commit dedf2e1
Show file tree

Hide file tree

Showing 43 changed files with 478 additions and 21 deletions.
diff --git 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
@@ -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
diff --git a/docs/img/auth0-token-generator.png b/docs/img/auth0-token-generator.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-version-navigator.png b/docs/img/feed-version-navigator.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/public-portal.png b/docs/img/public-portal.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/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
@@ -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).
+<div class="img-center">
+  ![schedule exception](../../img/schedule-exception.png)
+</div>
+
+## 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
@@ -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.
+<div class="img-center">
+  ![screenshot](../../img/edit-fare-rules.png)
+</div>
+
+## 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.
+<div class="img-center">
+  ![screenshot](../../img/add-fare-zone.png)
+</div>
+
+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
@@ -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.
+<div class="img-center">
+![quick access toolbar](../../img/quick-access-toolbar.png)
+</div>
+
+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 <a href="mailto:contact@conveyal.com">contact@conveyal.com</a> to see how we might be able to help.
diff --git a/docs/user/editor/patterns.md 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.
+<!-- TODO: add transitwand to GTFS Editor -->
+<!-- - Transitwand id (optional) – the trip pattern can be imported from a Transitwand route trace, if you have one enter the phone id here and click the ‘Load from Transitwand’ box. -->
+- **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`.
+<div class="img-center">
+![add stop from dropdown](../../img/pattern-add-stop.png)
+</div>
+
+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.
+<div class="img-center">
+![insert stop from map](../../img/pattern-insert-stop.png)
+</div>
+
+### Pattern stop toolbar
+The pattern stop toolbar can be found by clicking the pattern stop in the map view.
+<div class="img-center">
+![pattern stop toolbar](../../img/pattern-stop-toolbar.png)
+</div>
+
+- **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.
+<div class="img-center">
+![drag and drop pattern stop](../../img/pattern-stop-order.png)
+</div>
+
+**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
+
+<!-- TODO: clear pattern stops feature -->
+<!-- - Clear pattern – removes stop sequence from pattern -->
+
+## 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.
+<div class="img-center">
+![pattern shape editing options](../../img/pattern-shape-panel.png)
+</div>
+
+### 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
@@ -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)