7d0aeeefe5
* Improve format and clarity of the docs [ci skip] While this change produces a lot of git noise by enacting what seems like an arbitrary linewrap on most of the files in the documentation it will result in better version control and tracking of the changes in the documentation. For example, as it currently stands, if one was to make a PR to move a comma in a sentence because each paragraph in most of the files is on a single line, that small change would look in the git history like the author had modified the entire paragraph. In reality, this author just moved a comma. This change also includes a significant number of modifications to the more article-esque docs. Many of these docs were written in a sort of stream-of-conciousness and aren't as easy to read as they could be. Hopefully this is the first of several readability changes. If we could get these docs to a more accessible reading level, we would probably see an increase in contributions. :) * Delegate markdown wrapping to Prettier * Add linewrapping explanation in the docs [ci skip]
38 lines
1.2 KiB
Markdown
38 lines
1.2 KiB
Markdown
---
|
|
title: Contributing to the API Specification Docs
|
|
---
|
|
|
|
# Contributing to API spec docs
|
|
|
|
The API docs follow the [OpenAPI 3
|
|
specification](http://spec.openapis.org/oas/v3.0.2).
|
|
|
|
## Where the docs are located
|
|
|
|
We auto-generate the documentation from `api_v0.yml` within the `/docs`
|
|
directory. We use [ReDoc](https://github.com/Redocly/redoc) to turn the OpenAPI
|
|
3 format into a readable and searchable HTML documentation.
|
|
|
|
## Updating API docs
|
|
|
|
Whenever you make changes to the API docs, make sure to bump the version in
|
|
`api_v0.yml`.
|
|
|
|
## Running and editing the docs locally
|
|
|
|
If you want to browse the documentation locally you can use:
|
|
|
|
```shell
|
|
yarn api-docs:serve
|
|
```
|
|
|
|
This will let you browse the auto-generated version of the doc locally, and it
|
|
will reload the doc after every modification of the spec file.
|
|
|
|
If you have Visual Studio Code, we suggest you install the following extensions
|
|
that enable validation and navigation within the spec file:
|
|
|
|
- [OpenAPI (Swagger)
|
|
editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi)
|
|
- [openapi-designer live
|
|
preview](https://marketplace.visualstudio.com/items?itemName=philosowaffle.openapi-designer)
|