= Documentation

Good documentation is just as important as good code.footnote:[If not even more important.]
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 https://github.com/clojure-emacs/cider/tree/master/doc[doc] folder of CIDER's GitHub repo and is published to https://docs.cider.mx.
https://antora.org[Antora] is used to convert the AsciiDoc source into HTML.
Antora's filesystem layout is described https://docs.antora.org/antora/2.0/component-structure/[here].

== Installing Antora

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

Installing the Antora is super simple:

[source]
----
$ npm i -g @antora/cli@2.0 @antora/site-generator-default@2.0
----

Check out https://docs.antora.org/antora/2.0/install/install-antora/[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
https://github.com/clojure-emacs/cider/blob/master/doc/modules/ROOT/nav.adoc[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 https://github.com/clojure-emacs/docs.cider.mx[docs.cider.mx] repo.

[source,shell]
----
$ cd docs.cider.mx
$ antora antora-playbook.yml
----

== Deploying the Docs Site

NOTE: The manual will be regenerated manually periodically by CIDER's Core Team.

We're currently publishing the user manual to GitHub Pages.
The deployment process is simply pushing the generated HTML to GitHub. Simple as that.
There's a simple script in the documentation repository that automates the process of
fetching the latest updates and publishing them:

[source,shell]
----
$ cd docs.cider.mx
$ ./deploy
----

IMPORTANT: Don't forget to update the manual's version metadata when cutting CIDER releases.
It lives in `doc/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.
