How to: Add new annotations and extracted docs#
Example annotations and automated docs#
Annotations are a great way to keep documentation close to the code, but also be able to extract into documentation to be published on Readthedocs.
As an example, we have added feature toggle annotations to the edx-platform codebase. A Readthedocs document with the edx-platform feature toggles has been generated from them.
Add your own annotations and docs#
The following steps need to be performed to document new types of annotations in edx-platform. Adapt the final steps as appropriate for other services.
Define a new annotation format in code_annotations/contrib/config. See the feature toggle annotations as an example.
Create a Sphinx extension to collect these annotations. You can base it on the featuretoggles and settings extensions.
Read and update Sphinx extensions.
Add a new documentation page in the edx-platform technical docs that will use this Sphinx extension. Adapt this step as needed for other services.
As required, add custom linting for the new annotations to edx-lint. Again, follow the toggle and setting checkers as examples.