Working with Our Documentation

The documentation system of BRL-CAD is based on AsciiDoc and Antora.

Installing Antora

Install nvm:

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
source ~/.bashrc
command -v nvm

Install the latest Node LTS release:

nvm install --lts
node --version
nvm alias default 14

Install Antora:

npm i -g @antora/cli @antora/site-generator-default
antora -v

Install Antora site generator with Lunr:
```
npm i -g antora-site-generator-lunr
```

Building the Docs Locally

Get the code of the docs from GitHub:

git clone https://github.com/BRL-CAD/brlcad-docs

Generate the HTML files:
```
cd brlcad-docs/
antora build-dev.yml
```
As prescribed on build-dev.yml, the output will be stored on the directory html/.
To view the docs, open the HTML files on a browser (the location should be something like this: ~/brlcad-docs/html/docs/index.html).

Editing the Docs

Any text editor is OK, and most of them provide syntax highlighting for AsciiDoc. Some of them provide more advanced features, like live preview.

If you use Emacs, there is an adoc-mode for working with AsciiDoc files. Otherwise you can use one of the editors recommended on this page (which include Atom, Brackets, Eclipse, Visual Studio Code, etc.)

Whenever you make some changes, you need to rebuild the docs and refresh the browser in order to view them. The Bash script utils/watch.sh may be used to rebuild the docs automatically whenever there are some modifications.

Submitting Contributions

Assuming that you have write access on the BRL-CAD/brlcad-docs repository, you can commit and push your changes directly. However a better way is to follow the GitHub flow and make a pull request in order to get some review and feedback from other people, before these changes are merged to the main docs.

The workflow could be like this:

Before starting any changes create a new local branch, with a name that somehow describes the changes that are going to be made. For example:
```
git clone https://github.com/BRL-CAD/brlcad-docs
cd brlcad-docs/
git checkout -b update-the-hacking-book
```
Then start making the changes and testing them locally (by building the docs with antora build-dev.yml). Commit these changes to the local branch as well.
Push this branch to GitHub:
```
git push origin update-the-hacking-book
```
At this moment, if you go to https://github.com/BRL-CAD/brlcad-docs you will be able to create easily a pull request that aims to merge all the commits from the new branch to the main branch.
Then you can ask someone to review your changes. One way they can review your changes is by checking out your branch and building the docs locally:
```
git clone https://github.com/BRL-CAD/brlcad-docs
cd brlcal-docs/
git pull
git branch -a
git checkout update-the-hacking-book
antora build-dev.yml
```
To refine the changes, both of you can make new commits to the branch, and when you push them to GitHub they will appear automatically on the pull request.
When you are happy with the changes, you can merge the pull request and delete the branch from GitHub. You can delete the branch locally as well, like this:
```
git checkout main
git pull -p
git branch -a
git branch -d update-the-hacking-book
```