Update documentation with TypeSpec instructions and general changes

README.md

@@ -1,7 +1,28 @@
+<center>
+
+[![Build/Deploy OpenAPI specification](https://github.com/polyphony-chat/docs/actions/workflows/deploy-openapi-spec.yml/badge.svg)](https://github.com/polyphony-chat/docs/actions/workflows/deploy-openapi-spec.yml)
+[![mkdocs documentation](https://github.com/polyphony-chat/docs/actions/workflows/python-mkdocs.yml/badge.svg)](https://github.com/polyphony-chat/docs/actions/workflows/python-mkdocs.yml)
+[![Discord]][Discord-invite]
+[![Code-of-conduct-shield]][Code-of-conduct]
+
+[Discord]: https://img.shields.io/badge/Discord_Server-390075
+[Discord-invite]: https://discord.com/invite/m3FpcapGDD
+[Code-of-conduct-shield]: https://img.shields.io/badge/Code_of_Conduct-eb00ff
+[Code-of-conduct]: https://github.com/polyphony-chat/.github/blob/main/CODE_OF_CONDUCT.md
+
+</center>
+
 # Documentation
 
-Specification documents and API documentation for the polyproto federated messaging protocol
-Built with mkdocs-material and python3.12
+Specification documents and API documentation for the polyproto federated messaging protocol.
+
+Documentation built with mkdocs-material and python3.12
+
+API documentation built with [TypeSpec](https://typespec.io).
+
+## Pre-compiled OpenAPI schema(s)
+
+Find the pre-compiled OpenAPI schema file(s) in the [`/api/build`](https://github.com/polyphony-chat/docs/tree/main/api/build) directory. The schema is automatically built and deployed to the `main` branch on every push to the `main` branch.
 
 ## File structure
 
@@ -22,6 +43,8 @@ You should also read our [Code of Conduct](https://github.com/polyphony-chat/.gi
 
 ## Setting up a development environment
 
+### Documentation
+
 You will need the following things installed on your computer:
 
 - `python3.12`
@@ -33,3 +56,20 @@ Optionally, you can install [`vale`](https://vale.sh/) for spell-/grammar checki
 
 Use `pip install -r requirements.txt` to install the required dependencies, and `mkdocs build` or
 `mkdocs serve` to build the project or serve it on localhost.
+
+### API documentation
+
+You will need the following things installed on your computer:
+
+- `Node.js >= 20`
+- `npm`, `pnpm` or `yarn`
+- `git`
+- `TypeSpec` - install it globally with `npm install -g @typespec/compiler`
+
+1. Navigate to the `/api/src` directory.
+2. Select the project you want to compile. In this example, we are compiling the `core` project.
+   Navigate to that directory.
+3. Run `tsp install` to install the dependencies.
+4. Run `tsp compile .` to compile the project or `tsp compile --watch .` to automatically recompile
+   the project when you save a file.
+5. The compiled OpenAPI3 schema will be in the `$PROJECT/tsp-output/@typespec/openapi3` directory.