Documentation
Good documentation is just as important as good code.[1] CIDER is a pretty complex project with numerous features and the user manual is one of the primary ways to discover those. Please, consider improving and extending it.
Overview
The manual is generated from the asciidoc files in the doc folder of CIDER’s GitHub repo and is published to https://docs.cider.mx. Antora is used to convert the manual into HTML. The filesystem layout is described at https://docs.antora.org/antora/2.0/component-structure/
Installing Antora
| The instructions here assume you already have (the right version of) node.js installed. |
Installing the Antora is super simple:
$ npm i -g @antora/cli@2.0 @antora/site-generator-default@2.0Check out the detailed installation instructions if you run into any problems.
Editing the Docs
If you want to make changes to the manual’s page structure you’ll have to edit nav.adoc.
Building the Site
To make changes to the manual you simply have to change the files under doc.
You can build the documentation locally from the cider-site repo.
$ cd cider-site
$ antora site.ymlDeploying the Site
| The manual will be regenerated manually periodically by CIDER’s Core Team. |
The deployment process is simply pushing the generated HTML to GitHub. Simple as that.
Don’t forget to update the manual’s version metadata when cutting CIDER releases.
It lives in docs/antora.yml.
|
Down the road we plan to automate the process and deploy automatically changes to the manual. Ideally this should be done by our CI.