Encore.ts API docs refactoring (#1359)

Co-authored-by: André Eriksson <[email protected]>

README.md

@@ -125,7 +125,8 @@ Signup.Publish(ctx, &User{...})
 
 See how to use the Backend Frameworks in the docs:
 
-- **Services and APIs:** [Go](https://encore.dev/docs/primitives/services-and-apis) / [TypeScript](https://encore.dev/docs/ts/primitives/services-and-apis)
+- **Services:** [Go](https://encore.dev/docs/primitives/services-and-apis) / [TypeScript](https://encore.dev/docs/ts/primitives/services)
+- **APIs:** [Go](https://encore.dev/docs/primitives/services-and-apis) / [TypeScript](https://encore.dev/docs/ts/primitives/apis)
 - **Databases:** [Go](https://encore.dev/docs/primitives/databases) / [TypeScript](https://encore.dev/docs/ts/primitives/databases)
 - **Cron Jobs:** [Go](https://encore.dev/docs/primitives/cron-jobs) / [TypeScript](https://encore.dev/docs/ts/primitives/cron-jobs)
 - **Pub/Sub:** [Go](https://encore.dev/docs/primitives/pubsub) / [TypeScript](https://encore.dev/docs/ts/primitives/pubsub)

docs/menu.cue

@@ -326,12 +326,11 @@
 			text: "Testing"
 			path: "/develop/testing"
 			file: "develop/testing"
-			inline_menu: [{
-				kind: "basic"
-				text: "Mocking"
-				path: "/develop/testing/mocking"
-				file: "develop/mocking"
-			}]
+		}, {
+			kind: "basic"
+			text: "Mocking"
+			path: "/develop/testing/mocking"
+			file: "develop/mocking"
 		}, {
 			kind: "basic"
 			text: "Validation"
@@ -419,6 +418,11 @@
 			path: "/ts/concepts/benefits"
 			file: "ts/concepts/benefits"
 		}, {
+			kind: "basic"
+			text: "App Structure"
+			path: "/ts/develop/app-structure"
+			file: "ts/develop/app-structure"
+		},{
 			kind: "basic"
 			text: "Hello World"
 			path: "/ts/concepts/hello-world"
@@ -429,31 +433,39 @@
 		text: "Infrastructure"
 		items: [{
 			kind: "basic"
-			text: "Services and APIs"
-			path: "/ts/primitives/services-and-apis"
-			file: "ts/primitives/services-and-apis"
-			inline_menu: [{
+			text: "Services"
+			path: "/ts/primitives/services"
+			file: "ts/primitives/services"
+		}, {
+			kind: "accordion"
+			text: "APIs"
+			accordion: [{
 				kind: "basic"
-				text: "App Structure"
-				path: "/ts/develop/app-structure"
-				file: "ts/develop/app-structure"
+				text: "Defining APIs"
+				path: "/ts/primitives/apis"
+				file: "ts/primitives/apis"
 			}, {
 				kind: "basic"
-				text: "API Schemas"
-				path: "/ts/develop/api-schemas"
-				file: "ts/develop/api-schemas"
+				text: "API Calls"
+				path: "/ts/primitives/api-calls"
+				file: "ts/primitives/api-calls"
+			}, {
+				kind: "basic"
+				text: "Raw Endpoints"
+				path: "/ts/primitives/raw-endpoints"
+				file: "ts/primitives/raw-endpoints"
+			}, {
+				kind: "basic"
+				text: "Streaming APIs"
+				path: "/ts/primitives/streaming-apis"
+				file: "ts/primitives/streaming-apis"
 			}, {
 				kind: "basic"
 				text: "API Errors"
 				path: "/ts/develop/errors"
 				file: "ts/develop/errors"
 			}]
-		}, {
-			kind: "basic"
-			text: "Streaming APIs"
-			path: "/ts/primitives/streaming-apis"
-			file: "ts/primitives/streaming-apis"
-		}, {
+		},{
 			kind: "basic"
 			text: "Databases"
 			path: "/ts/primitives/databases"
@@ -586,12 +598,7 @@
 		text: "Flow Architecture Diagram"
 		path: "/observability/encore-flow"
 		file: "observability/encore-flow"
-	}, {
-		kind: "basic"
-		text: "Metrics"
-		path: "/observability/metrics"
-		file: "observability/metrics"
-	}, {
+	},{
 		kind: "basic"
 		text: "Service Catalog"
 		path: "/develop/api-docs"
@@ -622,6 +629,11 @@
 		text: "Preview Environments"
 		path: "/deploy/preview-environments"
 		file: "deploy/preview-environments"
+	}, {
+		kind: "basic"
+		text: "Metrics"
+		path: "/observability/metrics"
+		file: "observability/metrics"
 	}, {
 		kind: "basic"
 		text: "Connect your cloud account"
@@ -666,11 +678,6 @@
 		text: "Webhooks"
 		path: "/deploy/webhooks"
 		file: "deploy/webhooks"
-	}, {
-		kind: "basic"
-		text: "Integrating with Terraform"
-		path: "/deploy/terraform"
-		file: "deploy/terraform"
 	}]
 }
 
@@ -700,6 +707,11 @@
 			text: "Integrate with a web frontend"
 			path: "/how-to/integrate-frontend"
 			file: "how-to/integrate-frontend"
+		}, {
+			kind: "basic"
+			text: "Integrate with Terraform"
+			path: "/deploy/terraform"
+			file: "deploy/terraform"
 		}, {
 			kind: "basic"
 			text: "Use Temporal with Encore"

docs/quick-start.mdx

@@ -293,9 +293,9 @@ As you can see, it's all standard TypeScript.
 You define an API endpoint by wrapping a regular async function in a call to `api`. Doing this makes Encore identify the `hello` directory as a service,
 and that the `world` function is a public API endpoint. Encore automatically handles authentication, HTTP routing, request validation, error handling, observability, API documentation, and more.
 
-If you want to create more services and endpoints, you simply create new folders and define endpoints by wrapping functions in the `api` function. _If you're curious, you can read more about [defining services and APIs](/docs/ts/primitives/services-and-apis)._
+If you want to create more services and endpoints, you simply create new folders and define endpoints by wrapping functions in the `api` function. _If you're curious, you can read more about defining [services](/docs/ts/primitives/services) and [APIs](/docs/ts/primitives/apis)._
 
-Encore's [Backend Framework](/docs/ts) provides several declarative ways of using backend primitives like databases, Pub/Sub, and scheduled tasks by simply writing code.
+The Encore.ts [Backend Framework](/docs/ts) provides several declarative ways of using backend primitives like databases, Pub/Sub, and scheduled tasks by simply writing code.
 
 ## 3. Start your app & Explore Local Development Dashboard
 

docs/ts/concepts/benefits.md

@@ -13,22 +13,21 @@ lang: ts
 - **No manual configuration required**: No need for Infrastrucutre-as-Code. Your code is the single source of truth.
 - **Unified codebase**: One codebase for all environments; local, preview, and cloud.
 - **Cloud-agnostic by default**: Encore.ts provides an abstraction layer on top of the cloud provider's APIs, so you avoid becoming locked in to a single cloud.
-- **Evolve infrastructure without code changes**: As requirements evolve, you can change the provisioned infrastructure without making code changes, either using the Open Source [self-hosting tools](/docs/deploy/self-hosting) or fully-automated in your AWS/GCP account using [Encore's Cloud Platform](https://encore.dev/use-cases/devops-automation).
-cloud provider's console.
+- **Evolve infrastructure without code changes**: As requirements evolve, you can change the provisioned infrastructure without needing application code changes. Either using the Open Source [self-hosting tools](/docs/deploy/self-hosting) or with the optional [Cloud Platform](https://encore.dev/use-cases/devops-automation), which fully-automates infrastructure management in your own AWS/GCP account.
 
 ## High-performance Rust runtime
 
 To enable Encore's functionality in TypeScript, we’ve created a high-performance distributed systems runtime in Rust.
 It integrates with the standard Node.js runtime for excecuting JavaScript code, ensuring **100% compatability with the Node.js ecosystem**.
 
-It also provides a number of benefits over standard Node.js:
-- **Handles requests, API calls, databases, Pub/Sub, and observability**
+It provides a number of benefits over standard Node.js:
+- **Handles requests validation, provides API type-safety, has built-in observability, and integrates with databases, Pub/Sub, and more**
 - **9x increased throughput and 85% reduced latency** compared to standard Node.js/Express.js [See benchmarks](https://encore.dev/blog/event-loops)
 - **Zero NPM dependencies** for improved security and faster builds
 
 ### How it works
 
-Encore.ts is designed to let the Node.js event loop —which is single-threaded — focus on executing your business logic, while everything else happens in Encore’s multi-threaded Rust runtime. Here's a high-level overview of how this works:
+Encore.ts is designed to let the Node.js event loop — which is single-threaded — focus on executing your business logic, while everything else happens in Encore’s multi-threaded Rust runtime. Here's a high-level overview of how this works:
 
 **1. Node.js starts up and initializes the Encore Rust runtime. The Rust runtime then:**
    - Begins accepting incoming requests
@@ -53,13 +52,17 @@ Encore leverages static code analysis to parse the API schema and TypeScript typ
 
 ## No DevOps experience required
 
-Encore provides open source tools to help you integrate with your cloud infrastructure, enabling you to self-host your application anywhere to supports Docker containers.
+Encore provides open source tools to help you integrate with your cloud infrastructure, enabling you to self-host your application anywhere that supports Docker containers.
 Learn more in the [self-host documentation](/docs/deploy/self-hosting).
 
 You can also use [Encore's Cloud Platform](https://encore.dev/use-cases/devops-automation), which fully automates provisioning and managing infrastructure in your own cloud on AWS and GCP.
 
-This approach dramatically reduces the level of DevOps expertise required to use scalable, production-ready, cloud services like Kubernetes and Pub/Sub. And because your application code is the source of truth for infrastructure requirements, it ensures the infrastructure in all your environments are always in sync with the application's requirements.
+This approach dramatically reduces the level of DevOps expertise required to use scalable, production-ready, cloud services like Kubernetes and Pub/Sub. And because your application code is the source of truth for infrastructure requirements, it ensures the infrastructure in all environments is always in sync with the application's current requirements.
 
 ## Simplicity without giving up flexibility
 
-Encore.ts provides integrations for common infrastructure primitives, but also allows for flexibility. You can always use any cloud infrastructure, even if it's not built into Encore.ts. If you use Encore's [Cloud Platform](https://encore.dev/use-cases/devops-automation), it [automates infrastructure](/docs/deploy/infra) using your own cloud account, so you always have full access to your services from the cloud provider's console.
+Encore.ts provides integrations for common infrastructure primitives, but also allows for flexibility.
+
+For example, you can always use any cloud infrastructure, even if it's not built into the Encore.ts framework. You can use any database, message broker, or other service that your application needs, just set up the infrastructure and then reference it in your code as you would do traditionally.
+
+If you use Encore's [Cloud Platform](https://encore.dev/use-cases/devops-automation), it [automates infrastructure](/docs/deploy/infra) using your own cloud account, so you always have full access to your services from the cloud provider's console.

docs/ts/concepts/hello-world.md

@@ -43,8 +43,8 @@ Get to know the basics of Encore.ts in this getting started video.
 Encore's Backend Framework makes it simple to add more primitives, such as additional microservices, databases, Pub/Sub, etc.
 See how to use each primitive:
 
-- [Services and APIs](/docs/ts/primitives/services-and-apis)
-- [Streaming APIs](/docs/ts/primitives/streaming-apis)
+- [Services](/docs/ts/primitives/services)
+- [APIs](/docs/ts/primitives/apis)
 - [Databases](/docs/ts/primitives/databases)
 - [Cron Jobs](/docs/ts/primitives/cron-jobs)
 - [Pub/Sub & Queues](/docs/ts/primitives/pubsub)