Cleanup Documentation (#2797)

* move overview section to reference section. * move template to body section. * organize sidebar. * zio version.
zio · Apr 27, 2024 · 477157a · 477157a
1 parent 541eed2
commit 477157a
Show file tree

Hide file tree

Showing 26 changed files with 55 additions and 54 deletions.
diff --git a/build.sbt b/build.sbt
@@ -327,7 +327,8 @@ lazy val docs = project
     ),
     publish / skip                             := true,
     mdocVariables ++= Map(
-      "ZIO_SCHEMA_VERSION" -> ZioSchemaVersion
+      "ZIO_SCHEMA_VERSION" -> ZioSchemaVersion,
+      "ZIO_VERSION" -> ZioVersion
     )
   )
   .dependsOn(zioHttpJVM)

diff --git a/docs/faq.md b/docs/faq.md
@@ -18,7 +18,7 @@ If you prefer not to use ZIO HTTP but still want to build HTTP applications usin
 
 ### How Can I Serialize/Deserialize Data to/from JSON in Requests and Responses?
 
-ZIO HTTP provides built-in support for JSON serialization and deserialization using [ZIO Schema](https://zio.dev/zio-schema/). You can derive JSON codecs for your custom data types using ZIO Schema and use them to encode/decode data to/from request/response bodies. Check out the [BinaryCodecs](./binary_codecs.md) section in the documentation for more details.
+ZIO HTTP provides built-in support for JSON serialization and deserialization using [ZIO Schema](https://zio.dev/zio-schema/). You can derive JSON codecs for your custom data types using ZIO Schema and use them to encode/decode data to/from request/response bodies. Check out the [BinaryCodecs](./reference/body/binary_codecs.md) section in the documentation for more details.
 
 ### How Can I Handle CORS Requests in ZIO HTTP?
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -35,9 +35,9 @@ This template includes the following plugins:
 
 These dependencies in the g8 template were added to enable an efficient development process.
 
-### Hot-reload Changes
+### Hot-reload Changes (Watch Mode)
 
-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.
+[Sbt-revolver](https://github.com/spray/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:
 

diff --git a/docs/reference/handler_aspect.md → docs/reference/aop/handler_aspect.md b/docs/reference/handler_aspect.md → docs/reference/aop/handler_aspect.md
diff --git a/docs/reference/middleware.md → docs/reference/aop/middleware.md b/docs/reference/middleware.md → docs/reference/aop/middleware.md
@@ -213,7 +213,7 @@ val urlRewrite: Middleware[Any] =
 
 ## Built-in Middlewares
 
-In this section we are going to introduce built-in middlewares that are provided by ZIO HTTP. Please note that the `Middleware` object also inherits many other middlewares from the `HandlerAspect`, that we will introduce them on the [HandlerAspect](./handler_aspect.md) page.
+In this section we are going to introduce built-in middlewares that are provided by ZIO HTTP. Please note that the `Middleware` object also inherits many other middlewares from the `HandlerAspect`, that we will introduce them on the [HandlerAspect](handler_aspect.md) page.
 
 ### Access Control Allow Origin (CORS) Middleware
 

diff --git a/docs/reference/protocol-stack.md → docs/reference/aop/protocol-stack.md b/docs/reference/protocol-stack.md → docs/reference/aop/protocol-stack.md
diff --git a/docs/binary_codecs.md → docs/reference/body/binary_codecs.md b/docs/binary_codecs.md → docs/reference/body/binary_codecs.md
diff --git a/docs/reference/body.md → docs/reference/body/body.md b/docs/reference/body.md → docs/reference/body/body.md
diff --git a/docs/reference/form.md → docs/reference/body/form.md b/docs/reference/form.md → docs/reference/body/form.md
diff --git a/docs/reference/template.md → docs/reference/body/template.md b/docs/reference/template.md → docs/reference/body/template.md
diff --git a/docs/reference/client.md b/docs/reference/client.md
@@ -187,7 +187,7 @@ val program = for {
 ```
 
 :::note
-To learn more about headers and how they work, check out our dedicated section called [Header Operations](./headers.md#headers-operations) on the headers page.
+To learn more about headers and how they work, check out our dedicated section called [Header Operations](headers/headers.md#headers-operations) on the headers page.
 :::
 
 ## Composable URLs

diff --git a/docs/reference/endpoint.md b/docs/reference/endpoint.md
@@ -449,9 +449,9 @@ import utils._
 printSource("zio-http-example/src/main/scala/example/endpoint/GenerateEndpointFromOpenAPIExample.scala")
 ```
 
-## Generating ZIO‌ CLI App from Endpoint API
+## Generating ZIO CLI App from Endpoint API
 
-The ZIO‌ CLI is a ZIO‌ library that provides a way to build command-line applications using ZIO facilities. With ZIO‌ HTTP, we can generate a ZIO CLI client from the `Endpoint` API.
+The ZIO CLI is a ZIO library that provides a way to build command-line applications using ZIO facilities. With ZIO HTTP, we can generate a ZIO CLI client from the `Endpoint` API.
 
 To do this, first, we need to add the following line to the `build.sbt` file:
 

diff --git a/docs/reference/handler.md b/docs/reference/handler.md
@@ -582,7 +582,7 @@ Routes(
 )
 ```
 
-This will log every request coming to these handlers. ZIO HTTP supports various `HandlerAspects` that you can learn about in the [Middleware](middleware.md) section.
+This will log every request coming to these handlers. ZIO HTTP supports various `HandlerAspects` that you can learn about in the [Middleware](aop/middleware.md) section.
 
 ### Sandboxing Errors
 

diff --git a/docs/reference/headers.md → docs/reference/headers/headers.md b/docs/reference/headers.md → docs/reference/headers/headers.md
diff --git a/docs/reference/cookies.md → docs/reference/headers/session/cookies.md b/docs/reference/cookies.md → docs/reference/headers/session/cookies.md
diff --git a/docs/reference/flash.md → docs/reference/headers/session/flash.md b/docs/reference/flash.md → docs/reference/headers/session/flash.md
diff --git a/docs/overview.md → docs/reference/index.md b/docs/overview.md → docs/reference/index.md
@@ -1,19 +1,17 @@
 ---
-id: overview
-title: Overview
+id: index
+title: Introduction to ZIO HTTP
 ---
 
-**ZIO HTTP** is a powerful library that is used to build highly performant HTTP-based services and clients using functional scala and ZIO and uses [Netty](https://netty.io/) as its core.
-
-ZIO HTTP has powerful functional domains that help in creating, modifying, and composing apps easily. Let's start with the HTTP domain.
+ZIO HTTP offers an expressive API for creating HTTP applications. It uses a domain-specific language (DSL) to define routes and handlers. Both server and client are designed in terms of **HTTP as a function**, so they are functions from `Request` to `Response`.
 
 ## Core Concepts
 
-The core concepts of ZIO HTTP are:
+ZIO HTTP has powerful functional domains that help in creating, modifying, and composing apps easily. Let's take a look at the core domain:
 
 - `Routes` - A collection of `Route`s. If the error type of the routes is `Response`, then they can be served.
-- `Route` - A single route that can be matched against a http `Request` and produce a `Response`. It comprises a `RoutePattern` and a `Handler`:
-  1. `RoutePattern` - A pattern that can be matched against a http request. It is a combination of `Method` and `PathCodec` which can be used to match the method and path of the request.
+- `Route` - A single route that can be matched against an HTTP `Request` and produce a `Response`. It comprises a `RoutePattern` and a `Handler`:
+  1. `RoutePattern` - A pattern that can be matched against an HTTP `Request`. It is a combination of `Method` and `PathCodec` which can be used to match the `Method` and `Path` of the `Request`.
   2. `Handler` - A function that can convert a `Request` into a `Response`.
 
 Let's see each of these concepts inside a simple example:
@@ -61,9 +59,7 @@ object ExampleServer extends ZIOAppDefault {
 
 ### 1.Routes 
 
-The `Routes` provides input-dependent routing to different `Handler` values.
-
-The `Handler` and `Route` can be transformed to `Routes` by the `.toRoutes` method. To serve the routes, all errors should be handled by converting them into a `Response` using for example the `.handleError` method.
+The `Routes` is a collection of `Route` values. It can be created using its default constructor:
 
 ```scala mdoc:invisible
 import zio.http._
@@ -80,9 +76,13 @@ val app: Routes[Any, Response] =
     .handleError(e => Response.internalServerError(e.getMessage))
 ```
 
+The `Handler` and `Route` can be transformed to `Routes` by the `.toRoutes` method. To serve the routes, all errors should be handled by converting them into a `Response` using for example the `.handleError` method.
+
+For handling routes, ZIO HTTP has a [`Routes`](routing/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.
+
 ### 2. Route
 
-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`.
+Each `Route` is a combination of a [`RoutePattern`](routing/route_pattern.md) and a [`Handler`](handler.md). The `RoutePattern` is a combination of a `Method` and a [`PathCodec`](routing/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`:
 
@@ -97,7 +97,7 @@ val routes = Routes(
 )
 ```
 
-To learn more about routes, see the [Routes](reference/routes.md) page.
+To learn more about routes, see the [Routes](routing/routes.md) page.
 
 ### 3. Handler
 
@@ -140,7 +140,7 @@ val routes = Routes(
 )
 ```
 
-To learn more about the request, see the [Request](reference/request.md) page.
+To learn more about the request, see the [Request](request.md) page.
 
 ## Accessing Services from The Environment
 
@@ -198,7 +198,7 @@ val routes =
   )
 ```
 
-We have a more detailed explanation of the WebSocket connection on the [Socket](reference/socket/socket.md) page.
+We have a more detailed explanation of the WebSocket connection on the [Socket](socket/socket.md) page.
 
 ## Server
 
@@ -220,7 +220,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](reference/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](server.md) page.
 
 ## Client
 
@@ -243,4 +243,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](reference/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](client.md) page.
diff --git a/docs/reference/request.md b/docs/reference/request.md
@@ -230,7 +230,7 @@ Using the `Request#queryParameters` method, we can access the query parameters o
 
 ### Modifying Query Parameters
 
-When we are working with ZIO HTTP‌ Client, we need to create a new `Request` and may need to set/update/remove query parameters. In such cases, we have the following methods available: `addQueryParam`, `addQueryParams`, `removeQueryParam`, `removeQueryParams`, `setQueryParams`, and `updateQueryParams`.
+When we are working with ZIO HTTP Client, we need to create a new `Request` and may need to set/update/remove query parameters. In such cases, we have the following methods available: `addQueryParam`, `addQueryParams`, `removeQueryParam`, `removeQueryParams`, `setQueryParams`, and `updateQueryParams`.
 
 ```scala mdoc:compile-only
 import zio._

diff --git a/docs/reference/response.md → docs/reference/response/response.md b/docs/reference/response.md → docs/reference/response/response.md
@@ -353,4 +353,4 @@ Response.ok.addFlash(flash)
 
 ### Working with Headers
 
-There are various methods to work with headers in `Response` which we have discussed in the [Headers](headers.md#headers-operations) page.
+There are various methods to work with headers in `Response` which we have discussed in the [Headers](../headers/headers.md#headers-operations) page.
diff --git a/docs/reference/status.md → docs/reference/response/status.md b/docs/reference/status.md → docs/reference/response/status.md
@@ -1,6 +1,6 @@
 ---
 id: status
-title: Status Code
+title: Status Codes
 ---
 
 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/reference/path_codec.md → docs/reference/routing/path_codec.md b/docs/reference/path_codec.md → docs/reference/routing/path_codec.md
diff --git a/docs/reference/route_pattern.md → docs/reference/routing/route_pattern.md b/docs/reference/route_pattern.md → docs/reference/routing/route_pattern.md
diff --git a/docs/reference/routes.md → docs/reference/routing/routes.md b/docs/reference/routes.md → docs/reference/routing/routes.md
@@ -167,7 +167,7 @@ val routes: Routes[Any, Response] = ???
 val newRoutes = routes @@ HandlerAspect.dropTrailingSlash
 ```
 
-To learn more about middlewares, see the [Middleware](middleware.md) section.
+To learn more about middlewares, see the [Middleware](../aop/middleware.md) section.
 
 ## Handling Errors in Routes
 

diff --git a/docs/reference/server.md b/docs/reference/server.md
@@ -208,7 +208,7 @@ connection: close
 Hello World!⏎
 ```
 
-The‌ ZIO HTTP server by default supports keep-alive connections. To disable it, we can use the `Server.Config#keepAlive` method, by setting it to `false`:
+The ZIO HTTP server by default supports keep-alive connections. To disable it, we can use the `Server.Config#keepAlive` method, by setting it to `false`:
 
 ```scala mdoc:compile-only
 import zio.http._
@@ -546,7 +546,7 @@ printSource("zio-http-example/src/main/scala/example/ServeOnAnyOpenPort.scala")
 
 When a ZIO HTTP server is running, it handles incoming requests from clients, processes them, and sends back appropriate responses. In-flight requests are requests that have been received by the server but have not yet been fully processed or responded to. These requests might be in various stages of processing, such as waiting for database queries to complete or for resources to become available.
 
-When we're shutting down the server, it's important to handle these in-flight requests gracefully. ZIO‌ HTTP has a built-in mechanism to allow in-flight requests to finalize before shutting down the server. The default behavior is to wait for 10 seconds for in-flight requests to finalize before shutting down the server. During this time, the server will not accept new requests, but it will continue to process existing requests until they're fully completed.
+When we're shutting down the server, it's important to handle these in-flight requests gracefully. ZIO HTTP has a built-in mechanism to allow in-flight requests to finalize before shutting down the server. The default behavior is to wait for 10 seconds for in-flight requests to finalize before shutting down the server. During this time, the server will not accept new requests, but it will continue to process existing requests until they're fully completed.
 
 To change the default graceful shutdown timeout, we can use the `Server.Config#gracefulShutdownTimeout` method. It takes a `Duration` as an argument, and returns a new `Server.Config` with the specified graceful shutdown timeout:
 

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -7,10 +7,10 @@ const sidebars = {
       link: { type: "doc", id: "index" },
       items: [
         "installation",
-        "overview",
         {
           type: "category",
           collapsed: true,
+          link: { type: "doc", id: "reference/index" },
           label: "Reference",
           items: [
             "reference/server",
@@ -19,46 +19,48 @@ const sidebars = {
               type: "category",
               label: "Routing",
               items: [
-                "reference/routes",
-                "reference/route_pattern",
-                "reference/path_codec",
+                "reference/routing/routes",
+                "reference/routing/route_pattern",
+                "reference/routing/path_codec",
               ],
             },
             "reference/handler",
             {
               type: "category",
               label: "HTTP Messages",
               items: [
+                "reference/request",
+                "reference/response/response",
                 {
                   type: "category",
                   label: "Headers",
                   items: [
-                    "reference/headers",
-                    "reference/cookies",
-                    "reference/flash",
+                    "reference/headers/headers",
+                    "reference/headers/session/cookies",
+                    "reference/headers/session/flash",
                   ],
                 },
-                "reference/request",
-                {
-                  type: "category",
-                  label: "Response",
-                  items: ["reference/response", "reference/status"],
-                },
                 {
                   type: "category",
                   label: "Message Body",
-                  items: ["reference/body", "reference/form"],
+                  items: [
+                    "reference/body/body",
+                    "reference/body/form",
+                    "reference/body/binary_codecs",
+                    "reference/body/template",
+                  ],
                 },
+                "reference/response/status",
               ],
             },
             "reference/endpoint",
             {
               type: "category",
-              label: "HTTP Middleware",
+              label: "Aspects",
               items: [
-                "reference/protocol-stack",
-                "reference/middleware",
-                "reference/handler_aspect",
+                "reference/aop/protocol-stack",
+                "reference/aop/middleware",
+                "reference/aop/handler_aspect",
               ],
             },
             {
@@ -69,10 +71,8 @@ const sidebars = {
                 "reference/socket/websocketframe",
               ],
             },
-            "reference/template",
           ],
         },
-        "binary_codecs",
         "testing-http-apps",
         "faq",
         {

diff --git a/docs/testing-http-apps.md b/docs/testing-http-apps.md
@@ -33,8 +33,8 @@ object ExampleSpec extends ZIOSpecDefault {
 Also, ZIO HTTP provides a testkit called `zio-http-testkit` that includes `TestClient` and `TestServer` utilities which helps us to test our HTTP applications without the need for having a real live client and server instances.
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-test"         % ZioVersion  % Test
-libraryDependencies += "dev.zio" %% "zio-test-sbt"     % ZioVersion  % Test
+libraryDependencies += "dev.zio" %% "zio-test"         % "@ZIO_VERSION@"  % Test
+libraryDependencies += "dev.zio" %% "zio-test-sbt"     % "@ZIO_VERSION@"  % Test
 libraryDependencies += "dev.zio" %% "zio-http-testkit" % "@VERSION@" % Test
 testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")
 ```
-Original file line number
+Diff line change
@@ Expand Up / @@ -187,7 +187,7 @@ val program = for { @@
     ```
     :::note
-    To learn more about headers and how they work, check out our dedicated section called [Header Operations](./headers.md#headers-operations) on the headers page.
+    To learn more about headers and how they work, check out our dedicated section called [Header Operations](headers/headers.md#headers-operations) on the headers page.
     :::
     ## Composable URLs
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
Expand Up		@@ -353,4 +353,4 @@ Response.ok.addFlash(flash)

		### Working with Headers

		There are various methods to work with headers in `Response` which we have discussed in the [Headers](headers.md#headers-operations) page.
		There are various methods to work with headers in `Response` which we have discussed in the [Headers](../headers/headers.md#headers-operations) page.