From a38869bfcb0026f67acfb17f062424530700f30a Mon Sep 17 00:00:00 2001 From: bitfl0wer Date: Tue, 24 Dec 2024 13:41:46 +0100 Subject: [PATCH] Update documentation with TypeSpec instructions and general changes --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e445bdf4..a7fb9857 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,28 @@ +
+ +[![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 + +
+ # 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.