Editing the Orca Documentation
The documentation of Orca is published at https://docs.orca-app.dev/.
This document explains how this website is built and deployed, and how to edit it.
Overview
The documentation website is built with mkdocs from the markdown files found in doc/mkdocs.
Some docs like the index and quickstart guide are written manually, while the API reference is generated by a script.
The gen_doc.py python script loads the API description found in src/api.json, cross-checks the type information with the C header files, and outputs the API reference markdown files. It also generates the yaml file necessary for mkdocs to build the navigation bar of the website.
The website is build in CI and deployed through github pages when changes are pushed to the main branch.
Editing the Site Locally
Requirements
You need a recent version of python (3.10 or newer) and pip.
Install mkdocs:
pip install mkdocs
Install the libclang module, which is used to parse the C header files:
pip install libclang
Building and Serving Locally
Build the API markdown files and the mkdocs.yml file:
python scripts/gen_doc.py src/api.json doc/mkdocs
Serve the website locally:
cd doc/mkdocs
mkdocs serve
Then visit http://127.0.0.1:8000/ in your browser. Changes you make the markdown files should automatically trigger a reload and display the updated website.
Don't forget that the API reference and the mkdocs.yml file are generated:
- If you want to edit the API reference documentation, directly edit the documentation strings in
src/api.json. - If you want to make changes to the
mkdocs.ymlfile (for example to add a documentation section), editmkdocs_template.ymlfile instead.