Documentation: Reference Section on Sidebar (#2785)

* move dsl to reference. * remove unrelated index page. * introduce reference section. * better title. * revert bad commits. * revert more! * update sidebar. * update links.
zio · Apr 23, 2024 · 29ff8f6 · 29ff8f6
1 parent ca2937d
commit 29ff8f6
Show file tree

Hide file tree

Showing 25 changed files with 140 additions and 114 deletions.
diff --git a/docs/installation.md b/docs/installation.md
@@ -0,0 +1,66 @@
+---
+id: installation
+title: "Installation"
+---
+
+In this guide, we will learn how to get started with a new ZIO HTTP project.
+
+Before we dive in, we should make sure that we have the following on our computer:
+
+* JDK 1.8 or higher
+* sbt (scalaVersion >= 2.12)
+
+## Manual Installation
+
+To use ZIO HTTP, we should add the following dependencies in our project:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-http" % "@VERSION@"
+```
+
+## Using g8 Template
+
+To set up a ZIO Http project using the provided g8 template we can run the following command on our terminal:
+
+```shell
+sbt new zio/zio-http.g8
+```
+
+This template includes the following plugins:
+
+* [sbt-native-packager](https://github.com/sbt/sbt-native-packager)
+* [scalafmt](https://github.com/scalameta/scalafmt)
+* [scalafix](https://github.com/scalacenter/scalafix)
+* [sbt-revolver](https://github.com/spray/sbt-revolver)
+
+These dependencies in the g8 template were added to enable an efficient development process.
+
+### Hot-reload Changes
+
+Sbt-revolver can watch application resources for change and automatically re-compile and then re-start the application under development. This provides a fast development-turnaround, the closest we can get to real hot-reloading.
+
+We can start our application from _sbt_ with the following command:
+
+```shell
+~reStart
+```
+
+Pressing enter will stop watching for changes, but not stop the application. We can use the following command to stop the application (shutdown hooks will not be executed):
+
+```
+reStop
+```
+
+In case we already have an _sbt_ server running, i.e. to provide our IDE with BSP information, we should use _sbtn_ instead of _sbt_ to run `~reStart`, this lets both _sbt_ sessions share one server.
+
+### Formatting Source Code
+
+Scalafmt will automatically format all source code and assert that all team members use consistent formatting.
+
+### Refactoring and Linting
+
+Scalafix will mainly be used as a linting tool during everyday development, for example by removing unused dependencies or reporting errors for disabled features. Additionally, it can simplify upgrades of Scala versions and dependencies, by executing predefined migration paths.
+
+### SBT Native Packager
+
+The `sbt-native-packager` plugin can package the application in the most popular formats, for example, Docker images, RPM packages, or graalVM native images.
diff --git a/docs/overview.md b/docs/overview.md
@@ -86,7 +86,7 @@ val app: HttpApp[Any] =
 
 ### 2. Routes
 
-For handling routes, ZIO HTTP has a [`Routes`](dsl/routes.md) value, which allows us to aggregate a collection of individual routes. Behind the scenes, ZIO HTTP builds an efficient prefix-tree whenever needed to optimize dispatch.
+For handling routes, ZIO HTTP has a [`Routes`](reference/routes.md) value, which allows us to aggregate a collection of individual routes. Behind the scenes, ZIO HTTP builds an efficient prefix-tree whenever needed to optimize dispatch.
 
 The `Routes` is a collection of `Route` values. It can be created using its default constructor:
 
@@ -96,7 +96,7 @@ val routes = Routes(greetRoute, echoRoute)
 
 ### 3. Route
 
-Each `Route` is a combination of a [`RoutePattern`](dsl/route_pattern.md) and a [`Handler`](dsl/handler.md). The `RoutePattern` is a combination of a `Method` and a [`PathCodec`](dsl/path_codec.md) that can be used to match the method and path of the request. The `Handler` is a function that can convert a `Request` into a `Response`.
+Each `Route` is a combination of a [`RoutePattern`](reference/route_pattern.md) and a [`Handler`](reference/handler.md). The `RoutePattern` is a combination of a `Method` and a [`PathCodec`](reference/path_codec.md) that can be used to match the method and path of the request. The `Handler` is a function that can convert a `Request` into a `Response`.
 
 The `PathCodec` can be parameterized to extract values from the path. In such cases, the `Handler` should be a function that accepts the extracted values besides the `Request`:
 
@@ -111,7 +111,7 @@ val routes = Routes(
 )
 ```
 
-To learn more about routes, see the [Routes](dsl/routes.md) page.
+To learn more about routes, see the [Routes](reference/routes.md) page.
 
 ### 4. Handler
 
@@ -133,7 +133,7 @@ val randomGeneratorHandler =
   }
 ```
 
-There are several ways to create a `Handler`, to learn more about handlers, see the [Handlers](dsl/handler.md) page.
+There are several ways to create a `Handler`, to learn more about handlers, see the [Handlers](reference/handler.md) page.
 
 ## Accessing the Request
 
@@ -154,7 +154,7 @@ val routes = Routes(
 )
 ```
 
-To learn more about the request, see the [Request](dsl/request.md) page.
+To learn more about the request, see the [Request](reference/request.md) page.
 
 ## Accessing Services from The Environment
 
@@ -212,7 +212,7 @@ val routes =
   )
 ```
 
-We have a more detailed explanation of the WebSocket connection on the [Socket](dsl/socket/socket.md) page.
+We have a more detailed explanation of the WebSocket connection on the [Socket](reference/socket/socket.md) page.
 
 ## Server
 
@@ -234,7 +234,7 @@ object HelloWorld extends ZIOAppDefault {
 }
 ```
 
-Finally, we provided the default server with the port `8090` to the app. To learn more about the server, see the [Server](dsl/server.md) page.
+Finally, we provided the default server with the port `8090` to the app. To learn more about the server, see the [Server](reference/server.md) page.
 
 ## Client
 
@@ -257,4 +257,4 @@ object ClientExample extends ZIOAppDefault {
 }
 ```
 
-In the above example, we obtained the `Client` service from the environment and sent a `GET` request to the server. Finally, to run the client app, we provided the default `Client` and `Scope` services to the app. For more information about the client, see the [Client](dsl/client.md) page.
+In the above example, we obtained the `Client` service from the environment and sent a `GET` request to the server. Finally, to run the client app, we provided the default `Client` and `Scope` services to the app. For more information about the client, see the [Client](reference/client.md) page.
diff --git a/docs/dsl/body.md → docs/reference/body.md b/docs/dsl/body.md → docs/reference/body.md
diff --git a/docs/dsl/client.md → docs/reference/client.md b/docs/dsl/client.md → docs/reference/client.md
diff --git a/docs/dsl/cookies.md → docs/reference/cookies.md b/docs/dsl/cookies.md → docs/reference/cookies.md
diff --git a/docs/dsl/endpoint.md → docs/reference/endpoint.md b/docs/dsl/endpoint.md → docs/reference/endpoint.md
diff --git a/docs/dsl/flash.md → docs/reference/flash.md b/docs/dsl/flash.md → docs/reference/flash.md
diff --git a/docs/dsl/form.md → docs/reference/form.md b/docs/dsl/form.md → docs/reference/form.md
@@ -1,6 +1,6 @@
 ---
 id: form
-title: Form
+title: Form Data
 ---
 
 The `Form` represents a collection of `FormFields` that can be a multipart or URL-encoded form:

diff --git a/docs/dsl/handler.md → docs/reference/handler.md b/docs/dsl/handler.md → docs/reference/handler.md
@@ -1,6 +1,6 @@
 ---
 id: handler
-title: Handler
+title: Request Handler
 ---
 
 A `Handler` is responsible for processing the matched incoming request and generating an appropriate response. It is a function that takes a `Request` and produces a `Response`. Thus, it is a crucial component of the ZIO HTTP that determines how the server should respond to a request matched by the corresponding `RoutePattern`.

diff --git a/docs/dsl/handler_aspect.md → docs/reference/handler_aspect.md b/docs/dsl/handler_aspect.md → docs/reference/handler_aspect.md
diff --git a/docs/dsl/headers.md → docs/reference/headers.md b/docs/dsl/headers.md → docs/reference/headers.md
diff --git a/docs/dsl/middleware.md → docs/reference/middleware.md b/docs/dsl/middleware.md → docs/reference/middleware.md
diff --git a/docs/dsl/path_codec.md → docs/reference/path_codec.md b/docs/dsl/path_codec.md → docs/reference/path_codec.md
diff --git a/docs/dsl/protocol-stack.md → docs/reference/protocol-stack.md b/docs/dsl/protocol-stack.md → docs/reference/protocol-stack.md
diff --git a/docs/dsl/request.md → docs/reference/request.md b/docs/dsl/request.md → docs/reference/request.md
diff --git a/docs/dsl/response.md → docs/reference/response.md b/docs/dsl/response.md → docs/reference/response.md
diff --git a/docs/dsl/route_pattern.md → docs/reference/route_pattern.md b/docs/dsl/route_pattern.md → docs/reference/route_pattern.md
diff --git a/docs/dsl/routes.md → docs/reference/routes.md b/docs/dsl/routes.md → docs/reference/routes.md
diff --git a/docs/dsl/server.md → docs/reference/server.md b/docs/dsl/server.md → docs/reference/server.md
diff --git a/docs/dsl/socket/socket.md → docs/reference/socket/socket.md b/docs/dsl/socket/socket.md → docs/reference/socket/socket.md
diff --git a/docs/dsl/socket/websocketframe.md → docs/reference/socket/websocketframe.md b/docs/dsl/socket/websocketframe.md → docs/reference/socket/websocketframe.md
diff --git a/docs/dsl/status.md → docs/reference/status.md b/docs/dsl/status.md → docs/reference/status.md
@@ -1,6 +1,6 @@
 ---
 id: status
-title: Status 
+title: Status Code
 ---
 
 HTTP status codes are standard response codes given by web services on the Internet. The codes help identify the cause of the problem when a web page or other resource does not load properly.

diff --git a/docs/dsl/template.md → docs/reference/template.md b/docs/dsl/template.md → docs/reference/template.md
diff --git a/docs/setup.md b/docs/setup.md
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -2,53 +2,81 @@ const sidebars = {
   sidebar: [
     {
       type: "category",
-      label: "ZIO Http",
+      label: "ZIO HTTP",
       collapsed: true,
       link: { type: "doc", id: "index" },
       items: [
-        "setup",
+        "installation",
         "overview",
         {
           type: "category",
-          label: "DSL",
-          link: { type: "doc", id: "index" },
+          collapsed: true,
+          label: "Reference",
           items: [
-            "dsl/server",
-            "dsl/routes",
-            "dsl/route_pattern",
-            "dsl/path_codec",
-            "dsl/request",
-            "dsl/response",
-            "dsl/handler",
-            "dsl/headers",
-            "dsl/body",
-            "dsl/endpoint",
-            "dsl/form",
-            "dsl/cookies",
-            "dsl/flash",
-            "dsl/protocol-stack",
-            "dsl/middleware",
-            "dsl/handler_aspect",
-            "dsl/status",
+            "reference/server",
+            "reference/client",
+            {
+              type: "category",
+              label: "Routing",
+              items: [
+                "reference/routes",
+                "reference/route_pattern",
+                "reference/path_codec",
+              ],
+            },
+            "reference/handler",
+            {
+              type: "category",
+              label: "HTTP Messages",
+              items: [
+                {
+                  type: "category",
+                  label: "Headers",
+                  items: [
+                    "reference/headers",
+                    "reference/cookies",
+                    "reference/flash",
+                  ],
+                },
+                "reference/request",
+                {
+                  type: "category",
+                  label: "Response",
+                  items: ["reference/response", "reference/status"],
+                },
+                {
+                  type: "category",
+                  label: "Message Body",
+                  items: ["reference/body", "reference/form"],
+                },
+              ],
+            },
+            "reference/endpoint",
             {
               type: "category",
-              label: "DSL",
-              collapsed: false,
+              label: "HTTP Middleware",
               items: [
-                "dsl/socket/socket",
-                "dsl/socket/websocketframe"
-              ]
+                "reference/protocol-stack",
+                "reference/middleware",
+                "reference/handler_aspect",
+              ],
             },
-            "dsl/template",
-            "dsl/client"
-          ]
+            {
+              type: "category",
+              label: "WebSocket",
+              items: [
+                "reference/socket/socket",
+                "reference/socket/websocketframe",
+              ],
+            },
+            "reference/template",
+          ],
         },
         "binary_codecs",
         "testing-http-apps",
         {
           type: "category",
           label: "Examples",
-          collapsed: false,
           link: { type: "doc", id: "index" },
           items: [
             "examples/hello-world",
@@ -66,11 +94,11 @@ const sidebars = {
             "examples/concrete-entity",
             "examples/multipart-form-data",
             "examples/server-sent-events-in-endpoints",
-          ]
-        }
-      ]
-    }
-  ]
+          ],
+        },
+      ],
+    },
+  ],
 };
 
 module.exports = sidebars;