Working with Our Documentation
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
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
To view the docs, open the HTML files on a browser (the location should be something like this:
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
may be used to rebuild the docs automatically whenever there are some
Assuming that you have write access on the
repository, you can
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