Merge pull request #547 from LACMTA/dev

Documentation Update!
LACMTA · Jul 19, 2024 · a450518 · a450518
2 parents f7038dd + bcdd43d
commit a450518
Show file tree

Hide file tree

Showing 12 changed files with 263 additions and 241 deletions.
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -1,20 +1,20 @@
 {
     "version": "2.0.0",
     "tasks": [
-        {
-            "label": "Docker: Compose Up",
-            "type": "shell",
-            "command": "docker compose build && docker compose up",
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            },
-            "presentation": {
-                "reveal": "always",
-                "panel": "dedicated",
-                "showReuseMessage": false,
-            },
-            "problemMatcher": []
-        }
-    ]
+		{
+			"label": "Docker: Compose Up",
+			"type": "shell",
+			"command": "docker compose build && docker compose up",
+			"group": {
+				"kind": "build",
+				"isDefault": true
+			},
+			"presentation": {
+				"reveal": "always",
+				"panel": "dedicated",
+				"showReuseMessage": false
+			},
+			"problemMatcher": []
+		}
+	]
 }
diff --git a/architecture.md b/architecture.md
@@ -0,0 +1,25 @@
+# Architecture
+
+This document describes the architecture of Metro API 2.x, including the backend, frontend, database, and API components. It provides an overview of the technologies used in the project and the repository structure.
+
+## Overview
+
+The project is built using the following technologies:
+
+- **Frontend**: The frontend is built using [React](https://reactjs.org/) and [Docusaurus](https://docusaurus.io/), a modern static website generator. It provides a user-friendly interface for interacting with the Metro API.
+- **Backend**: The backend is built using [FastAPI](https://fastapi.tiangolo.com/), a modern web framework for building APIs with Python. It provides the logic for handling requests to the Metro API and serves as the interface between the frontend and the Metro API.
+- **Database**: The project uses a [PostgreSQL](https://www.postgresql.org/) database to store data related to the Metro API, such as routes, stops, and schedules. The database is accessed using the [SQLAlchemy](https://www.sqlalchemy.org/) ORM.
+- **API**: The Metro API provides access to real-time data, GTFS data, and other information related to the Los Angeles Metro system. It is built using FastAPI and provides endpoints for retrieving data about routes, stops, schedules, and live transit updates.
+- **WebSocket**: The Metro API also supports WebSocket connections to receive real-time updates about vehicles and trips. This allows developers to receive updates on vehicle positions or trip updates in real-time. Mainly the web socket is used as a pass-through for the Swiftly API.
+
+## Repository Structure
+
+The project repository is structured as follows:
+
+- **`documentation/`**: Contains documentation for the project built on Docusaurus and using the plugin `docusaurus-plugin-redoc` to generate API documentation from OpenAPI specifications.
+- **`fastapi/`**: Contains the FastAPI backend code for the Metro API, including routes, models, and logic for handling requests.
+- **`data-loading-service`**: Contains the code for the data loading service that loads data from the Metro API into the PostgreSQL database.
+- **`notebooks/`**: Contains Jupyter notebooks for data analysis and exploration.
+- **`docker-compose.yml`**: Contains the Docker Compose configuration for running the project locally.
+- **`README.md`**: Contains the project README with information about setting up and running the project.
+
diff --git a/documentation/README.md b/documentation/README.md
@@ -1,28 +1,9 @@
 # Template
 
-This template is built for [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This template is built for [Docusaurus 3](https://docusaurus.io/), a modern static website generator.
 
 ### Usage
 
-```bash
-npx [email protected] my-website --package-manager yarn
-```
-
-> When prompted to select a template choose `Git repository`.
-
-Template Repository URL:
-
-```bash
-https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
-```
-
-> When asked how the template repo should be cloned choose "copy" (unless you know better).
-
-```bash
-cd my-website
-yarn
-```
-
 ### Local Development
 
 ```bash

diff --git a/documentation/blog/2021-08-01-mdx-blog-post.mdx b/documentation/blog/2021-08-01-mdx-blog-post.mdx
diff --git a/documentation/blog/2023-03-19-long-blog-post.md b/documentation/blog/2023-03-19-long-blog-post.md
diff --git a/documentation/blog/2023-03-20.mdx b/documentation/blog/2023-03-20.mdx
diff --git a/documentation/blog/2023-03-21.mdx b/documentation/blog/2023-03-21.mdx
diff --git a/documentation/blog/2023-03-29.mdx b/documentation/blog/2023-03-29.mdx
diff --git a/documentation/blog/authors.yml b/documentation/blog/authors.yml
diff --git a/documentation/docs/intro.md b/documentation/docs/intro.md
@@ -1,45 +1,87 @@
----
-sidebar_position: 1
----
+# Welcome to the Los Angeles Metro User Guide
 
-# Tutorial Intro
+This guide provides an overview of the Los Angeles Metro API, including key features, common tasks, and troubleshooting tips. The developer side of this documentation is geared towards developers of the Los Angeles Metro API.
 
-Let's discover **the Metro API in less than 5 minutes** by creating a webpage.
+## Overview
 
-## Getting Started
+The Metro API provides access for developers to retrieve real-time data, GTFS data, and other information related to the Los Angeles Metro system. By leveraging this API, you can access detailed information about routes, stops, schedules, and live transit updates.
 
-Get started by **creating a new site**.
+- **Real-Time Data:** Access up-to-the-minute information on bus and train schedules, including delays and cancellations.
+- **GTFS Data:** Explore detailed information about routes, stops, and schedules.
+- **Canceled Service Data:** Stay informed about any service disruptions or cancellations that might affect your journey.
+- **Static Data:** Explore detailed information about routes, stops, and schedules to plan your trip effectively.
+- **Other Data:** Access additional resources like Gopass Schools information.
 
-### What you'll need
+## How to Use Key Features
 
-- [Node.js](https://nodejs.org/en/download/) version 16.14 or above:
-  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
+### Accessing Real-Time Data
 
-## Generate a new site
+To receive real-time updates about vehicles and trips, connect to our WebSocket endpoint. This endpoint is a pass-through for the Swiftly API, providing updates on vehicle positions or trip updates.
 
-Generate a new Docusaurus site using the **classic template**.
+#### How It Works:
 
-The classic template will automatically be added to your project after you run the command:
+1. **Connect to the WebSocket:** Use the endpoint format above to establish a WebSocket connection.
+2. **Receive Updates:** Once connected, you will receive real-time updates every 3 seconds. Updates include information about vehicle positions or trip updates, depending on the `endpoint` parameter specified.
+3. **Data Format:** Updates are sent in JSON format, including details such as `vehicle_id`, `route_code`, and trip information.
+4. **Error Handling:** If an error occurs while processing updates, an error message will be sent in the format `"Error: error_message"`.
 
-```bash
-npm init docusaurus@latest my-website classic
+#### Example Update Format:
+
+```json
+{
+    "id": "vehicle_id",
+    "vehicle": {
+        "trip": {
+            "route_id": "route_code",
+            ...
+        },
+        ...
+    },
+    "route_code": "route_code",
+    ...
+}
 ```
+### Accessing GTFS Data
 
-You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
+- **Get All Agencies:** Use the `/agencies` endpoint to view a list of all available agencies.
+- **Get Agency Routes:** Access `/routes/{agency_id}` to view all routes for a specific agency.
+- **Get Route Stops:** Use `/stops/{agency_id}/{route_code}` to view all stops for a specific route.
+- **Get Stop Times:** Access `/stop_times/{agency_id}/{route_code}` to view stop times for a specific route.
+- **Get Trips:** Use `/trips/{agency_id}/{trip_id}` to view details about a specific trip.
+- **Get All Trips:** Access `/trips/{agency_id}` to view all trips for a specific agency.
+- **Get All Routes:** Use `/routes/{agency_id}` to view all routes for a specific agency.
+- **Get All Stops:** Access `/stops/{agency_id}` to view all stops for a specific agency.
+- **Get All Stop Times:** Use `/stop_times/{agency_id}` to view all stop times for a specific agency.
 
-The command also installs all necessary dependencies you need to run Docusaurus.
 
-## Start your site
+### Checking Canceled Service Data
 
-Run the development server:
+- **Get Canceled Trip Summary:** Use `/canceled_service_summary` to view a summary of all canceled trips.
+- **Get Canceled Trip:** To find details about canceled trips for a specific line, use `/canceled_service/line/{line}`.
+- **View All Canceled Trips:** Access `/canceled_service/all` to see all canceled trips.
 
-```bash
-cd my-website
-npm run start
-```
+### Exploring Static Data
+
+- **Route and Stop Information:** Use endpoints like `/{agency_id}/route_stops/{route_code}` and `/{agency_id}/stops/{stop_id}` to get information about routes and stops.
+- **Schedule and Trip Details:** Access detailed schedule information with endpoints such as `/{agency_id}/stop_times/route_code/{route_code}` and `/{agency_id}/trips/{trip_id}`.
+- **Route Overview:** Get an overview of routes with `/{agency_id}/route_overview` or detailed information for a specific route with `/{agency_id}/route_overview/{route_code}`.
+
+## Examples of Common Tasks
+
+- **How to Check for Service Alerts:** Use the canceled service data endpoints to check for any disruptions or cancellations.
+- **How to Find Real-Time Schedule Information:** Utilize the real-time data endpoints to get the latest schedule updates for your route.
+
+## Troubleshooting Tips
+
+- **Issue: The schedule seems outdated.** Solution: Ensure you're accessing the real-time data endpoints for the most current information.
+- **Issue: Can't find my route.** Solution: Double-check the route code or use the `/{agency_id}/routes` endpoint to search for all available routes.
+
+## Support and Contact Information
 
-The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
+For further assistance or to provide feedback, please contact our customer support team:
 
-The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
+- **Email:** [email protected]
+- **Phone:** 1-800-LA-METRO
+- **Live Chat:** Available on our web application during business hours.
 
-Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
+We're here to help make your Los Angeles Metro experience as smooth and enjoyable as possible. Start exploring today and take the hassle out of public transit!