Documentation development

OSCAR uses MKDocs for the documentation. In particular, Material for MKDocs.

When linking from one page under docs/ to another OSCAR documentation page, prefer relative links such as fdl.md or api.md. This keeps links inside the currently selected version when the site is published with mike.

Install the following dependencies:

pip install mkdocs mkdocs-material mkdocs-render-swagger-plugin mike

The from the main folder oscar run:

mkdocs serve

The documentation will be available in http://127.0.0.1:8000

API documentation

To generate the OpenAPI spec from swagger comments:

swag init -g main.go -o pkg/apidocs

To serve the generated swagger.json locally with Swagger UI:

docker run --rm -p 8081:8080 \
  -e SWAGGER_JSON=/docs/swagger.json \
  -v "$(pwd)/pkg/apidocs/swagger.json:/docs/swagger.json" \
  swaggerapi/swagger-ui

Then open http://localhost:8081 to browse the API.