From 473e5aa772a4231c14c34b58402f45e283987320 Mon Sep 17 00:00:00 2001
From: Spencer Ferris <3319370+spencewenski@users.noreply.github.com>
Date: Mon, 14 Oct 2024 17:44:18 -0700
Subject: [PATCH] docs: Add features list outline (#433)

---
 book/src/SUMMARY.md                           | 47 ++++++++++++++-----
 book/src/ch-03-01-features-http.md            |  1 -
 book/src/ch-03-02-features-middleware.md      |  1 -
 book/src/ch-03-03-features-app-state.md       |  1 -
 book/src/ch-03-04-features-openapi.md         |  1 -
 book/src/ch-03-05-features-tracing.md         |  1 -
 book/src/ch-03-06-features-configuration.md   |  0
 .../actix.md}                                 |  4 +-
 .../axum.md}                                  |  9 ++--
 .../index.md}                                 |  0
 book/src/comparisons/leptos.md                |  1 +
 book/src/comparisons/loco.md                  |  1 +
 book/src/comparisons/poem.md                  |  1 +
 book/src/features/app-context.md              |  1 +
 book/src/features/auth/index.md               |  1 +
 book/src/features/auth/jwt.md                 |  1 +
 book/src/features/cli.md                      |  1 +
 book/src/features/configuration.md            |  1 +
 book/src/features/database/index.md           |  1 +
 book/src/features/database/user.md            |  1 +
 .../features/database/utility-migrations.md   |  1 +
 book/src/features/email/index.md              |  1 +
 book/src/features/email/sendgrid.md           |  1 +
 book/src/features/email/smtp.md               |  1 +
 book/src/features/health.md                   |  1 +
 .../index.md}                                 |  0
 book/src/features/lifecycle.md                |  1 +
 book/src/features/open-api.md                 |  1 +
 .../services/background-jobs/index.md         |  1 +
 .../services/background-jobs/sidekiq.md       |  1 +
 book/src/features/services/function.md        |  1 +
 book/src/features/services/grpc.md            |  1 +
 book/src/features/services/http/index.md      |  1 +
 .../src/features/services/http/initializer.md |  1 +
 book/src/features/services/http/middleware.md |  1 +
 book/src/features/services/http/state.md      |  1 +
 book/src/features/services/index.md           |  1 +
 book/src/features/testing.md                  |  1 +
 book/src/features/tracing/index.md            |  1 +
 book/src/features/tracing/otel.md             |  1 +
 .../index.md}                                 |  0
 ...{ch-00-introduction.md => introduction.md} |  4 +-
 42 files changed, 73 insertions(+), 25 deletions(-)
 delete mode 100644 book/src/ch-03-01-features-http.md
 delete mode 100644 book/src/ch-03-02-features-middleware.md
 delete mode 100644 book/src/ch-03-03-features-app-state.md
 delete mode 100644 book/src/ch-03-04-features-openapi.md
 delete mode 100644 book/src/ch-03-05-features-tracing.md
 delete mode 100644 book/src/ch-03-06-features-configuration.md
 rename book/src/{ch-01-02-comparisons-actix.md => comparisons/actix.md} (76%)
 rename book/src/{ch-01-01-comparisons-axum.md => comparisons/axum.md} (74%)
 rename book/src/{ch-01-00-comparisons.md => comparisons/index.md} (100%)
 create mode 100644 book/src/comparisons/leptos.md
 create mode 100644 book/src/comparisons/loco.md
 create mode 100644 book/src/comparisons/poem.md
 create mode 100644 book/src/features/app-context.md
 create mode 100644 book/src/features/auth/index.md
 create mode 100644 book/src/features/auth/jwt.md
 create mode 100644 book/src/features/cli.md
 create mode 100644 book/src/features/configuration.md
 create mode 100644 book/src/features/database/index.md
 create mode 100644 book/src/features/database/user.md
 create mode 100644 book/src/features/database/utility-migrations.md
 create mode 100644 book/src/features/email/index.md
 create mode 100644 book/src/features/email/sendgrid.md
 create mode 100644 book/src/features/email/smtp.md
 create mode 100644 book/src/features/health.md
 rename book/src/{ch-03-00-features.md => features/index.md} (100%)
 create mode 100644 book/src/features/lifecycle.md
 create mode 100644 book/src/features/open-api.md
 create mode 100644 book/src/features/services/background-jobs/index.md
 create mode 100644 book/src/features/services/background-jobs/sidekiq.md
 create mode 100644 book/src/features/services/function.md
 create mode 100644 book/src/features/services/grpc.md
 create mode 100644 book/src/features/services/http/index.md
 create mode 100644 book/src/features/services/http/initializer.md
 create mode 100644 book/src/features/services/http/middleware.md
 create mode 100644 book/src/features/services/http/state.md
 create mode 100644 book/src/features/services/index.md
 create mode 100644 book/src/features/testing.md
 create mode 100644 book/src/features/tracing/index.md
 create mode 100644 book/src/features/tracing/otel.md
 rename book/src/{ch-02-00-getting-started.md => getting-started/index.md} (100%)
 rename book/src/{ch-00-introduction.md => introduction.md} (92%)

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index d5d143ad..49135420 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -1,15 +1,38 @@
 # Summary
 
-[Introduction](ch-00-introduction.md)
+[Introduction](introduction.md)
 
-- [Web framework comparisons](ch-01-00-comparisons.md)
-    - [Roadster vs. Axum](ch-01-01-comparisons-axum.md)
-    - [Roadster vs. Actix](ch-01-02-comparisons-actix.md)
-- [Getting started](ch-02-00-getting-started.md)
-- [Roadster features](ch-03-00-features.md)
-    - [HTTP Service with Axum](ch-03-01-features-http.md)
-    - [Axum middleware](ch-03-02-features-middleware.md)
-    - [Axum state](ch-03-03-features-app-state.md)
-    - [OpenAPI with Aide](ch-03-04-features-openapi.md)
-    - [Tracing](ch-03-05-features-tracing.md)
-    - [Configuration](ch-03-06-features-configuration.md)
+- [Web framework comparisons](comparisons/index.md)
+    - [Roadster vs. Loco](comparisons/loco.md)
+    - [Roadster vs. Poem](comparisons/poem.md)
+    - [Roadster vs. Axum](comparisons/axum.md)
+    - [Roadster vs. Actix](comparisons/actix.md)
+    - [Roadster vs. Leptos](comparisons/leptos.md)
+- [Getting started](getting-started/index.md)
+- [Roadster features](features/index.md)
+    - [Configuration](features/configuration.md)
+    - [App context](features/app-context.md)
+    - [Database](features/database/index.md)
+        - [User SQL migrations](features/database/user.md)
+        - [Utility SQL migrations](features/database/utility-migrations.md)
+    - [Services](features/services/index.md)
+        - [HTTP Service with Axum](features/services/http/index.md)
+            - [Axum State](features/services/http/state.md)
+            - [Axum Middleware](features/services/http/middleware.md)
+            - [Initializers](features/services/http/initializer.md)
+        - [Background jobs](features/services/background-jobs/index.md)
+            - [Sidekiq](features/services/background-jobs/sidekiq.md)
+        - [Grpc service with Tonic](features/services/grpc.md)
+        - [Function service](features/services/function.md)
+    - [Auth](features/auth/index.md)
+        - [JWT](features/auth/jwt.md)
+    - [OpenAPI with Aide](features/open-api.md)
+    - [Email](features/email/index.md)
+        - [SMTP](features/email/smtp.md)
+        - [Sendgrid](features/email/sendgrid.md)
+    - [Tracing](features/tracing/index.md)
+        - [OpenTelemetry](features/tracing/otel.md)
+    - [CLI](features/cli.md)
+    - [Health checks](features/health.md)
+    - [Lifecycle hooks](features/lifecycle.md)
+    - [Testing](features/testing.md)
diff --git a/book/src/ch-03-01-features-http.md b/book/src/ch-03-01-features-http.md
deleted file mode 100644
index be8bf08d..00000000
--- a/book/src/ch-03-01-features-http.md
+++ /dev/null
@@ -1 +0,0 @@
-# HTTP Service with Axum
\ No newline at end of file
diff --git a/book/src/ch-03-02-features-middleware.md b/book/src/ch-03-02-features-middleware.md
deleted file mode 100644
index 5664e74e..00000000
--- a/book/src/ch-03-02-features-middleware.md
+++ /dev/null
@@ -1 +0,0 @@
-# Axum middleware
diff --git a/book/src/ch-03-03-features-app-state.md b/book/src/ch-03-03-features-app-state.md
deleted file mode 100644
index 48f56d5e..00000000
--- a/book/src/ch-03-03-features-app-state.md
+++ /dev/null
@@ -1 +0,0 @@
-# Axum state
diff --git a/book/src/ch-03-04-features-openapi.md b/book/src/ch-03-04-features-openapi.md
deleted file mode 100644
index 06987374..00000000
--- a/book/src/ch-03-04-features-openapi.md
+++ /dev/null
@@ -1 +0,0 @@
-# OpenAPI with Aide
diff --git a/book/src/ch-03-05-features-tracing.md b/book/src/ch-03-05-features-tracing.md
deleted file mode 100644
index 6c328cf4..00000000
--- a/book/src/ch-03-05-features-tracing.md
+++ /dev/null
@@ -1 +0,0 @@
-# Tracing
diff --git a/book/src/ch-03-06-features-configuration.md b/book/src/ch-03-06-features-configuration.md
deleted file mode 100644
index e69de29b..00000000
diff --git a/book/src/ch-01-02-comparisons-actix.md b/book/src/comparisons/actix.md
similarity index 76%
rename from book/src/ch-01-02-comparisons-actix.md
rename to book/src/comparisons/actix.md
index b0164ced..61ba54af 100644
--- a/book/src/ch-01-02-comparisons-actix.md
+++ b/book/src/comparisons/actix.md
@@ -1,6 +1,6 @@
-# Roadster vs. [Actix](https://actix.rs/)
+# Roadster vs. [Actix](https://crates.io/crates/actix-web)
 
-As mentioned in [Roadster vs. Axum](ch-01-01-comparisons-axum.md), Roadster uses [Axum](https://crates.io/crates/axum)
+As mentioned in [Roadster vs. Axum](axum.md), Roadster uses [Axum](https://crates.io/crates/axum)
 to provide an HTTP server, so it's probably more relevant to compare Actix and Axum. A quick internet search can provide
 various comparisons, some are included below:
 
diff --git a/book/src/ch-01-01-comparisons-axum.md b/book/src/comparisons/axum.md
similarity index 74%
rename from book/src/ch-01-01-comparisons-axum.md
rename to book/src/comparisons/axum.md
index 3f598807..76d571d0 100644
--- a/book/src/ch-01-01-comparisons-axum.md
+++ b/book/src/comparisons/axum.md
@@ -4,15 +4,16 @@ Roadster actually uses Axum to provide an HTTP server, so anything you can do wi
 However, using Roadster has some benefits compared to configuring Axum yourself:
 
 - Roadster registers a collection of common middleware with sensible default configurations. The configurations can also
-  be customized easily via config files. See [Axum middleware](ch-03-02-features-middleware.md) for more information.
+  be customized easily via config files. See [Axum middleware](../features/services/http/middleware.md) for more
+  information.
 - Roadster creates an `AppContext` to use as the Axum State that contains all the dependency objects created by
   Roadster, such as the DB connection, app config, etc. This can also be extended using
   Axum's [FromRef](https://docs.rs/axum/latest/axum/extract/derive.FromRef.html) if you need to provide additional state
   to your Axum routes.
-  See [Axum state](ch-03-03-features-app-state.md) for more
+  See [Axum state](../features/services/http/state.md) for more
   information.
 - Roadster supports registering API routes using [Aide](https://crates.io/crates/aide) to enable auto-generating an
-  OpenAPI schema and playground. See [OpenAPI with Aide](ch-03-04-features-openapi.md) for more information.
+  OpenAPI schema and playground. See [OpenAPI with Aide](../features/open-api.md) for more information.
 - Roadster auto-generates a unique request ID for each request, if one wasn't provided in the request
 - Roadster configures the [Tracing](https://crates.io/crates/tracing) crate and enables instrumentation for requests.
-  See [Tracing](ch-03-05-features-tracing.md) for more information.
+  See [Tracing](../features/tracing/index.md) for more information.
diff --git a/book/src/ch-01-00-comparisons.md b/book/src/comparisons/index.md
similarity index 100%
rename from book/src/ch-01-00-comparisons.md
rename to book/src/comparisons/index.md
diff --git a/book/src/comparisons/leptos.md b/book/src/comparisons/leptos.md
new file mode 100644
index 00000000..e972100b
--- /dev/null
+++ b/book/src/comparisons/leptos.md
@@ -0,0 +1 @@
+# Roadster vs. [Leptos](https://crates.io/crates/leptos)
diff --git a/book/src/comparisons/loco.md b/book/src/comparisons/loco.md
new file mode 100644
index 00000000..91411c8d
--- /dev/null
+++ b/book/src/comparisons/loco.md
@@ -0,0 +1 @@
+# Roadster vs. [Loco](https://crates.io/crates/loco-rs)
diff --git a/book/src/comparisons/poem.md b/book/src/comparisons/poem.md
new file mode 100644
index 00000000..0839fff8
--- /dev/null
+++ b/book/src/comparisons/poem.md
@@ -0,0 +1 @@
+# Roadster vs. [Poem](https://crates.io/crates/poem)
diff --git a/book/src/features/app-context.md b/book/src/features/app-context.md
new file mode 100644
index 00000000..13bb64f7
--- /dev/null
+++ b/book/src/features/app-context.md
@@ -0,0 +1 @@
+# App context
diff --git a/book/src/features/auth/index.md b/book/src/features/auth/index.md
new file mode 100644
index 00000000..7ad9c149
--- /dev/null
+++ b/book/src/features/auth/index.md
@@ -0,0 +1 @@
+# Auth
diff --git a/book/src/features/auth/jwt.md b/book/src/features/auth/jwt.md
new file mode 100644
index 00000000..62ca8c2b
--- /dev/null
+++ b/book/src/features/auth/jwt.md
@@ -0,0 +1 @@
+# JWT
diff --git a/book/src/features/cli.md b/book/src/features/cli.md
new file mode 100644
index 00000000..3f213d43
--- /dev/null
+++ b/book/src/features/cli.md
@@ -0,0 +1 @@
+# CLI
diff --git a/book/src/features/configuration.md b/book/src/features/configuration.md
new file mode 100644
index 00000000..a025a48b
--- /dev/null
+++ b/book/src/features/configuration.md
@@ -0,0 +1 @@
+# Configuration
diff --git a/book/src/features/database/index.md b/book/src/features/database/index.md
new file mode 100644
index 00000000..f1f9cc0c
--- /dev/null
+++ b/book/src/features/database/index.md
@@ -0,0 +1 @@
+# Database
diff --git a/book/src/features/database/user.md b/book/src/features/database/user.md
new file mode 100644
index 00000000..f237b61a
--- /dev/null
+++ b/book/src/features/database/user.md
@@ -0,0 +1 @@
+# User SQL migrations
diff --git a/book/src/features/database/utility-migrations.md b/book/src/features/database/utility-migrations.md
new file mode 100644
index 00000000..0762d0b0
--- /dev/null
+++ b/book/src/features/database/utility-migrations.md
@@ -0,0 +1 @@
+# Utility SQL migrations
diff --git a/book/src/features/email/index.md b/book/src/features/email/index.md
new file mode 100644
index 00000000..88e4d47a
--- /dev/null
+++ b/book/src/features/email/index.md
@@ -0,0 +1 @@
+# Email
diff --git a/book/src/features/email/sendgrid.md b/book/src/features/email/sendgrid.md
new file mode 100644
index 00000000..ce15d560
--- /dev/null
+++ b/book/src/features/email/sendgrid.md
@@ -0,0 +1 @@
+# Sendgrid
diff --git a/book/src/features/email/smtp.md b/book/src/features/email/smtp.md
new file mode 100644
index 00000000..870f70fc
--- /dev/null
+++ b/book/src/features/email/smtp.md
@@ -0,0 +1 @@
+# SMTP
diff --git a/book/src/features/health.md b/book/src/features/health.md
new file mode 100644
index 00000000..0b438ce2
--- /dev/null
+++ b/book/src/features/health.md
@@ -0,0 +1 @@
+# Health checks
diff --git a/book/src/ch-03-00-features.md b/book/src/features/index.md
similarity index 100%
rename from book/src/ch-03-00-features.md
rename to book/src/features/index.md
diff --git a/book/src/features/lifecycle.md b/book/src/features/lifecycle.md
new file mode 100644
index 00000000..52ee6cba
--- /dev/null
+++ b/book/src/features/lifecycle.md
@@ -0,0 +1 @@
+# Lifecycle hooks
diff --git a/book/src/features/open-api.md b/book/src/features/open-api.md
new file mode 100644
index 00000000..10c03f9a
--- /dev/null
+++ b/book/src/features/open-api.md
@@ -0,0 +1 @@
+# OpenAPI with [Aide](https://crates.io/crates/aide)
diff --git a/book/src/features/services/background-jobs/index.md b/book/src/features/services/background-jobs/index.md
new file mode 100644
index 00000000..81945087
--- /dev/null
+++ b/book/src/features/services/background-jobs/index.md
@@ -0,0 +1 @@
+# Background jobs
diff --git a/book/src/features/services/background-jobs/sidekiq.md b/book/src/features/services/background-jobs/sidekiq.md
new file mode 100644
index 00000000..9f66e257
--- /dev/null
+++ b/book/src/features/services/background-jobs/sidekiq.md
@@ -0,0 +1 @@
+# Background jobs with [Sidekiq.rs](https://crates.io/crates/rusty-sidekiq)
diff --git a/book/src/features/services/function.md b/book/src/features/services/function.md
new file mode 100644
index 00000000..c50b6737
--- /dev/null
+++ b/book/src/features/services/function.md
@@ -0,0 +1 @@
+# Function service
diff --git a/book/src/features/services/grpc.md b/book/src/features/services/grpc.md
new file mode 100644
index 00000000..dc831fa0
--- /dev/null
+++ b/book/src/features/services/grpc.md
@@ -0,0 +1 @@
+# Grpc service with [Tonic](https://crates.io/crates/tonic)
diff --git a/book/src/features/services/http/index.md b/book/src/features/services/http/index.md
new file mode 100644
index 00000000..65b079ec
--- /dev/null
+++ b/book/src/features/services/http/index.md
@@ -0,0 +1 @@
+# HTTP Service with [Axum](https://crates.io/crates/axum)
diff --git a/book/src/features/services/http/initializer.md b/book/src/features/services/http/initializer.md
new file mode 100644
index 00000000..991efa91
--- /dev/null
+++ b/book/src/features/services/http/initializer.md
@@ -0,0 +1 @@
+# Initializers
diff --git a/book/src/features/services/http/middleware.md b/book/src/features/services/http/middleware.md
new file mode 100644
index 00000000..67088412
--- /dev/null
+++ b/book/src/features/services/http/middleware.md
@@ -0,0 +1 @@
+# Axum Middleware
diff --git a/book/src/features/services/http/state.md b/book/src/features/services/http/state.md
new file mode 100644
index 00000000..2e850b63
--- /dev/null
+++ b/book/src/features/services/http/state.md
@@ -0,0 +1 @@
+# Axum State
diff --git a/book/src/features/services/index.md b/book/src/features/services/index.md
new file mode 100644
index 00000000..8e5b66bc
--- /dev/null
+++ b/book/src/features/services/index.md
@@ -0,0 +1 @@
+# Services
diff --git a/book/src/features/testing.md b/book/src/features/testing.md
new file mode 100644
index 00000000..f00b526a
--- /dev/null
+++ b/book/src/features/testing.md
@@ -0,0 +1 @@
+# Testing
diff --git a/book/src/features/tracing/index.md b/book/src/features/tracing/index.md
new file mode 100644
index 00000000..7afc67ed
--- /dev/null
+++ b/book/src/features/tracing/index.md
@@ -0,0 +1 @@
+# Tracing with Tokio's [tracing](https://crates.io/crates/tracing) crate
diff --git a/book/src/features/tracing/otel.md b/book/src/features/tracing/otel.md
new file mode 100644
index 00000000..7353df02
--- /dev/null
+++ b/book/src/features/tracing/otel.md
@@ -0,0 +1 @@
+# OpenTelemetry
diff --git a/book/src/ch-02-00-getting-started.md b/book/src/getting-started/index.md
similarity index 100%
rename from book/src/ch-02-00-getting-started.md
rename to book/src/getting-started/index.md
diff --git a/book/src/ch-00-introduction.md b/book/src/introduction.md
similarity index 92%
rename from book/src/ch-00-introduction.md
rename to book/src/introduction.md
index 92e69a1e..c12c59ee 100644
--- a/book/src/ch-00-introduction.md
+++ b/book/src/introduction.md
@@ -13,8 +13,8 @@ customizable, and pluggable. This allows you to focus on creating your applicati
 dependencies, while still allowing you the flexibility to customize your dependencies if needed.
 
 If you're unsure if Roadster is the best fit for your project, a collection of comparisons to other Rust web frameworks
-can be found in [Web framework comparisons](ch-01-00-comparisons.md). The full list of Roadster's features can be
-found in [Roadster features](ch-03-00-features.md).
+can be found in [Web framework comparisons](comparisons/index.md). The full list of Roadster's features can be
+found in [Roadster features](features/index.md).
 
 ## Prerequisite reading