Add a Documentation Page

Documentation for opa-java is managed using MkDocs. You can build the docs into a folder out using the command ./scripts/build_docs.sh, or you can serve an ephemeral, local version of the docs using ./scripts/serve_docs.sh.

Appropriate Content for Docs

The docs site for opa-java is primarily for maintenance information about the project. Information about how to use specific APIs belongs in the JavaDoc, and can be created or modified by changing comments in the Java code. Higher-level user-facing documentation belongs on the Styra documentation site.

Generally speaking, the MkDocs site should only contain information that would be of interest to someone contributing to the opa-java repo.

Adding a Document

1. Add your document to docs/site/docs/.
2. Update docs/site/mkdocs.yml so that your document will be presented in the navigation bar.
3. Update docs/site/docs/index.md to include a link to your new document.
4. Use scripts/build_doc.sh or scripts/serve_docs.sh to ensure your docs changes render as you intended.
5. Create a PR with your changes. Your changes will automatically be published by the docs publishing workflow.