Skip to content

Documentation guidelines

First of all, you should become a member of the CABLE-LSM GitHub organisation prior to contribute to the CABLE's documentation. Please ask for membership on this issue. All guidelines and implementation details are written with the assumption you are a member of the organisation.

The documentation for CABLE has two parts:

  • inline documentation in the source code. This documentation includes the detailed scientific documentation. It is written using FORD.
  • the standalone guides such as the User Guide and the Developer Guide. It is written using Material for MkDocs.

Both tools use Markdown and LaTeX Mathematics for formatting.

Documentation workflow

All documentation is located in the CABLE GitHub repository. To update the documentation, you need to follow the CABLE contribution guidelines.

Scientific documentation

The scientific documentation should be added directly into the source code available under the src/ directory. Please use these guidelines to structure the documentation. You can find a cheatsheet for FORD on this page.

Other documentation

Other documentation such as the User guide and Developer guide are located under the documentation/docs/ folder. Each file corresponds to a page on the rendered documentation and each folder corresponds to a tab or a section. Folders and files are named very similarly to the sections and pages on the documentation website to help navigation when developing the documentation.
To help you find the file corresponding to a page, on the rendered documentation website, you can click on the pen icon at the top right. This will open the corresponding file in GitHub and show you the path to the file. If you need more help to contribute to the User guide or the Developer guide, please use the contribution guide for ACCESS-Hive.