4.2. Documentation#
The vantage6 framework is documented on this website. Additionally, there is API Documenation with OAS3+. This documentation is shipped directly with the server instance. All of these documentation pages are described in more detail below.
4.2.1. How this documentation is created#
The source of the documentation you are currently reading is located
here, in the docs
folder of the vantage6 repository itself.
To build the documentation locally you can use the Makefile
located in the
docs
folder. The command make html
will generate these pages in HTML.
To automatically rebuild the documentation whenever you make a change, you can
use sphinx-autobuild. Assuming
you are in the main directory of the repository, run the following command:
pip install sphinx-autobuild
sphinx-autobuild docs docs/_build/html --watch .
Then you can access the documentation on http://127.0.0.1:8000
. The
--watch
option makes sure that if you make changes to either the
documentation text or the docstrings, the documentation pages will also be
reloaded.
This documentation is automatically built and published on a commit (on
certain branches, including main
). Both Frank and Bart have access to the
vantage6 project when logged into readthedocs. Here they can manage which
branches are to be synced, manage the webhook used to trigger a build, and some
other -less important- settings.
The files in this documentation use the rst
format, to see the syntax view
this cheatsheet.
4.2.2. API Documenation with OAS3+#
The API documentation is hosted at the server at the /apidocs
endpoint. This documentation is generated from the docstrings using Flasgger. The source of this documentation can be found in the docstrings of the API functions.
If you are unfamiliar with OAS3+, note that it was formerly known as Swagger.
- An example of such a docsting:
"""Summary of the endpoint --- description: >- Short description on what the endpoint does, and which users have access or which permissions are required. parameters: - in: path name: id schema: type: integer description: some identifier required: true responses: 200: description: Ok 401: description: Unauthorized or missing permission security: - bearerAuth: [] tags: ["Group"] """