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 AsciiDoc source into HTML. Antora’s filesystem layout is described here.

Installing Antora

The instructions here assume you already have (the right version of) node.js installed.

Installing the Antora is super simple:

$ npm install

Check 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 Docs Site

To make changes to the manual you simply have to change the files under doc.

You can build the documentation locally from the docs.cider.mx repo.

$ git clone https://github.com/clojure-emacs/docs.cider.mx
$ cd docs.cider.mx
$ make build

To check the generated site you can simply open build/site/index.html in your favourite browser.

Deploying the Docs Site

The manual will be regenerated manually periodically by CIDER’s Core Team.

We’re currently publishing the user manual to GitHub Pages. The deployment is handled by a GitHub Actions workflow that builds and deploys the documentation every time something is changed in the documentation site’s repository. It can also be triggered manually if needed.

Updating the Playbook

Don’t forget to update the manual’s version metadata when cutting CIDER releases. It lives in doc/antora.yml.

When cutting new releases you’ll have to updated antora-playbook.yml to mention their relevant tags from which the documentation needs to be build. Here’s how this looks for one of the projects:

- url: https://github.com/clojure-emacs/cider.git
  branches: master
  tags: ['v1.7.0', 'v1.8.0']
  start_path: docs
You need to add one such block for each new CIDER module you’re adding to the docs site.

Troubleshooting

The most common mistake that people make is to forget to update the version of an Antora docs module after cutting a release. This will result in an error saying you’ve got the same version in two branches (e.g. master and v1.0). Fixing this is pretty simple - just update the version to master in antora.yml.

1. If not even more important.