Building LSDTopoTools documentation

1. The LSDTopoTools documentation toolchain

Most users will just look at our website. But some users may wish to build the documents themselves. The documents are built using Asciidoctor, which is a Ruby documentation engine.

Just tell me how to build the documentation

There are two paths to building the documentation.
Path 1: Use our dockerfile (this automatically builds the toolchain).
Path 2: Have a linux operating system and install the toolchain by hand. *
Once you have the toolchain, from the main repository directory run the python script compile_LSDTTDocs.py.

2. Building the documentation the easy way with docker

Docker is software for building containers. It works on Linux systems, MacOS, and Windows 10 Enterprise. If you are a Windows user but don’t have Windows 10 Enterprise, I am afraid you will need to build a virtual windows machine using something like virtual box.

First install docker. You can install it for Windows 10 and MacOS, Ubuntu, or Debian. A number of other linux environments are also available.
Build a docker container with the dockerfile from our documentation repository: build -t lsdtt_docs .
Download the documentation repository somewhere.

Run the docker container with a link to the documentation:

$ docker run -it -v /path/to/documentation:/documents/LSDTT_documents lsdtt_docs bash

When that container is running, go into the documentation directory and run our python script:
```
# cd LSDTT_documentation
# python compile_LSDTTDocs.py
```
The resulting website will be in the directory html_build.

Some notes on installing Ruby for LSDTopoTools by hand.

If you have built documentation using docker (the previous section) you can skip this section.

After a number of painful windows installations, we have decided that life in Linux is much easier. If you don’t have Linux you can make a little Linux machine in your own computer using virtualbox and vagrant, or using Docker. You can read about setting up one of these Linux machines in the LSDTopoTools installation instructions.

We will assume you are using Ubuntu in a Vagrant box or Docker container. If you are not on an Ubuntu system you will need to replace the apt-get commands with whatever command work on your operating system (e.g., yum). After trying a number of options, we have found that rvm is the best way to get everything working.
Open a terminal in your Linux system. If you don’t know what that is read our introduction to Linux.

We need to install some software first:

$ sudo apt-get install software-properties-common
$ sudo apt-add-repository -y ppa:rael-gc/rvm
$ sudo apt-get update
$ sudo apt-get install rvm

You will then need to log out of your Linux system and log back in again. rvm will tell you this:

Creating group 'rvm'

Installing RVM to /usr/share/rvm/
Installation of RVM in /usr/share/rvm/ is almost complete:

  * First you need to add all users that will be using rvm to 'rvm' group,
    and logout - login again, anyone using rvm will be operating with `umask u=rwx,g=rwx,o=rx`.

  * To start using RVM you need to run `source /etc/profile.d/rvm.sh`
    in all your open shell windows, in rare cases you need to reopen all shell windows.

In vagrant you can run vagrant halt and vagrant up; in Docker just shut down and re-start the container. Then do this:
```
$ source /etc/profile.d/rvm.sh
```
To see what users are in the group:
```
$ getent group rvm
```

To add the vagrant user:

$ sudo usermod -a -G rvm vagrant
$ getent group rvm

In my installation you cannot just start installing stuff, you need to open a new terminal. So use either ssh (Linux or MacOS) or putty.exe (windows) to open a new terminal.
In your new terminal run (Warning: this takes a long time!):
```
$ rvm install 2.3
```
I wanted to make sure we use this ruby default:
```
$ rvm use --default 2.3
```
Then install bundler:
```
$ gem install bundler
```

Now I went into a documentation folder and used bundle install. The gemfile is:

source 'https://rubygems.org'

gem 'rake'
gem 'asciidoctor'

gem 'json'
gem 'awesome_print'

gem 'asciidoctor-epub3'
gem 'asciidoctor-pdf'

gem 'coderay'
gem 'pygments.rb'
gem 'thread_safe'
gem 'epubcheck'

Yay, all the gems are installed!
The installation of the gem nokogiri can be very temperamental, one particular issue on MacOS is that its install clashes with The Silver Searcher. To resolve this issue, first run brew unlink xz to remove symlinks to xz, then re-run bundle install and once that completes, reapply the symlinks to xz: brew link xz.

3. Building the html documents in individual folders or all at once.

Make sure bundle install works on any of the gemfiles in the subdirectories of the documentation.
If you go into any subdirectory, you can now compile that section with:
```
$ bundle exec rake book:build_html
```
You can imagine that doing this in every folder is really tedious. We made a python script to compile everything at once.
Go into the main documentation directory.
Run:
```
$ python compile_LSDTTDocs.py
```
This will put the complete website in the html_build folder.

3.1. If you want to make pdf files using asciidoctor with equations in them

Forget about doing this in Windows. Follow the instructions above on getting rvm installed on Linux.

First, you need to install a bunch of stuff (this works in Ubuntu):

$ sudo apt-get -qq -y install bison flex libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev libpango1.0-dev ttf-lyx

Now run bundle install with this Gemfile:

source 'https://rubygems.org'

gem 'rake'
gem 'asciidoctor'

gem 'json'
gem 'awesome_print'

gem 'asciidoctor-mathematical'
gem 'asciidoctor-epub3'
gem 'asciidoctor-pdf'

gem 'coderay'
gem 'pygments.rb'
gem 'thread_safe'
gem 'epubcheck'

In our documentation pages this gemfile is usually stored under the name Gemfile_pdf.gem. To bundle install from this gemfile you use the command:
```
$ bundle install --gemfile=Gemfile_pdf
```
Troubleshooting: the Mathematical gem sometimes doensn’t work (or sadly, often doesn’t work). If this happens, run:
```
$ MATHEMATICAL_SKIP_STRDUP=1 gem install mathematical
```
Installing this takes an age!
Now, this is annoying. To get the pdf to work, you need to designate an :imagesoutdir: but a relative path will not work. So you need an absolute path in your root .asc file. So, for example, the root .asc file should contain the directives:
```
:stem: latexmath
:imagesoutdir: /LSDTopoTools/Git_projects/LSDTopoTools_ChiMudd2014/Documentation/images
```
You need to change this line to suit your path!

4. If you are making changes to the documentation

You can ignore this unless you are helping write the template and have push permission. Currently this applies to nobody so they are more notes for myself to remember how I set up this repository.

I do not want any messy merging conflicts! To avoid this please keep the master and gh-pages separate on your computer!

When checking out the code, check them out into two directories:

$ git clone https://github.com/LSDtopotools/LSDTT_documentation.git master
$ git clone https://github.com/LSDtopotools/LSDTT_documentation.git gh-pages

In the gh-pages directory, check out the gh-pages branch and get rid of the master branch:
```
$ cd gh-pages
$ git checkout origin/gh-pages -b gh-pages
$ git branch -d master
```
Now, go back to the master branch, you can make changes there.
You can use the python script compile_LSDTTDocs.py to compile all the documentation in the repository. This will create a website in the html_build folder.
If you want things to appear on the github website, you need to copy the files in the html_build folder (but not the .git folder) to the gh-pages directory.

Then go to the gh-pages directory and add any new files:

$ pwd
/some/path/to/LSDTT_documentation/master
$ cd ..
$ cd gh-pages
$ git add *.html
$ cd images
$ git add *.png *.jpg *.gif *.svg
$ cd ..
$ git commit -m "Updating website" .
$ git push origin gh-pages