Skip to content

Contribution guidelines

The online docs are generated from the main branch, therefore you must create pull requests against the main branch to update the docs.

There are two ways to contribute a pull request to the docs repository:

  1. You can click the Edit this page option at the top of every page on https://kleene.dev/.

    This opens the GitHub editor, which means you don't need to know a lot about Git, or even about Markdown. When you save, Git prompts you to create a fork if you don't already have one, and to create a branch in your fork and submit the pull request.

  2. Fork the docs GitHub repository. Suggest changes or add new content on your local branch, and submit a pull request (PR) to the main branch.

    This is the manual, more advanced version of clicking 'Edit this page' on a published docs page. Initiating a docs change in a PR from your own branch gives you more flexibility, as you can submit changes to multiple pages or files under a single pull request, and even create new topics.

Have a look at some of the .md files to see how to make a header for a new page. The left-hand navigation is defined in docs/SUMMARY.md.

Files not edited here

Most of Klee and Kleened's reference docs are generated from their repositories so pull requests against these files will be rejected.

This concerns:

  • docs/reference/kleened/kleened-*.yaml files (generated by make update-docs-openapi in the kleened dev environment)
  • data/klee-reference/*.yaml files (generated by make docs in the klee repository)

The pages under docs/reference/klee/ are generated at build time from those YAML files, so they do not exist as source files at all.

Pull request guidelines

Help us review your PRs more quickly by following these guidelines.

  • Try not to touch a large number of files in a single PR if possible.
  • Don't change whitespace or line wrapping in parts of a file you are not editing for other reasons. Make sure your text editor is not configured to automatically reformat the whole file when saving.
  • We highly recommend that you build and test the docs locally before submitting a PR.

Build and preview the docs locally

Start by cloning the repository and setting up the build dependencies (the setup target creates a .venv and installs the pinned requirements.txt):

$ git clone https://github.com/kleene-project/docs.git
$ cd docs
$ make setup

Then build and serve the docs with MkDocs' dev webserver:

$ make serve
INFO    -  Building documentation...
INFO    -  Documentation built in 11.23 seconds
INFO    -  [19:00:00] Serving on http://127.0.0.1:8000/

Voila! It's time to preview changes. Note that every time a change is made, MkDocs rebuilds the site automatically. Running .venv/bin/mkdocs build --strict (the same command CI runs) locally catches broken links and files missing from the navigation before the CI does.