A new platform has been chosen to host the CABLE documentation following these criteria:
- the documentation is easily discoverable
- the code developers need to update the documentation and the code together
- most people should be able to contribute to the documentation
- documentation for different versions of the code is easily identifiable
The new documentation is available through GitHub pages with the source of the documentation hosted in a GitHub repository. This repository will eventually host the CABLE code as well. The documentation is using two tools:
- Material for mkdocs to write the standalone documentation such as the User Guide and Developer Guide. It is possible to build mkdocs documentation with versioning, e.g. using mike.
- FORD for automatic documentation directly from the source code. This tool automatically builds information about arguments in procedures and various call graphs. We will add additional information about the purpose of each procedure and module through the use of markup comments.
Both tools use Markdown to format the text which is a simple, extensively used markup language. Other tools use the same format: GitHub, ACCESS-Hive, this forum etc.
The documentation is still in the early stages of being rewritten. Any help would be welcome. We are still deciding how to organise the documentation and how to organise the workload, any suggestion would be welcome.