LSDTopoTools Documentation

This is the master documentation for all of LSDTopoTools, a topographic analysis package.

The main landing page of the documentation can be found here: https://lsdtopotools.github.io/LSDTT_documentation/

1. Details that you don’t need to know about unless you are an lsdtt developer

This documentation has been written in asciidoc format, using the extended functionality of asciidoctor. Asciidoc is similar to markdown but we at LSDTopoTools like the added features of asciidoc and asciidoctor.

It is organised into subfolders, each of which can be compiled by asciidoctor into an hml or pdf.

2. Reading the documentation offline

If you want to read the documentation offline, you can go into the html_build directory and open index.html in your favourite browser.

You can also compile a pdf version using asciidoctor. See below.

3. Getting asciidoctor to work

If you do not want to edit or compile the documentation, read no further. Just go to the documentation website: https://lsdtopotools.github.io/LSDTT_documentation/

Still here? Okay, you can read our instructions on getting asciidoctor to work: https://lsdtopotools.github.io/LSDTT_documentation/LSDTT_building_documentation.html

3.1. Quickstart asciidoctor install

Installing asciidoctor can be a bit annoying as you need to do some fancy Ruby stuff. We have made a Docker container so you don’t need to do any of that. But you need to install docker.

1. Install docker. On MacOS and Linux this should be easy. On Windows you will need Windows 10 Enterprise. Sorry. The internet explains how to do everything.

2. Open a terminal/powershell window and download our docker container:

   $ docker pull lsdtopotools/lsdtt_docs_docker

3. You will need to set up an LSDTopoTools directory on your computer. You can run the container by linking it to your computer with:

   $ docker run -it -v C:\LSDTopoTools\LSDTT_documentation:/documents lsdtopotools/lsdtt_docs_docker

4. For more detail see: https://hub.docker.com/r/lsdtopotools/lsdtt_docs_docker

4. Compiling all the documentation

We have made a python script that builds each section of the documentation and then copies the resulting images and .html files to the directory html_build. To run this script you mush have asciidoctor installed.

The python script is here: https://github.com/LSDtopotools/LSDTT_documentation/blob/master/compile_LSDTTDocs.py

Run the script with:

$ python compile_LSDTTDocs.py

This will build the entire website in html_build on your computer.

5. Working on this documentation

If you want to update this documentation you will need to clone it. We do not want messy errors between the master and gh-pages branches. To properly clone the repository

1. When checking out the code, check them out into two directories (you should make a base LSDTT_documentation directory first):

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

2. 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

3. Now, go back to the master branch, you can make changes there.

4. When you commit changes to the master branch and you want to update the website, commit and push changes, then run bundle:

   $ pwd
   my/path/to/repo/LSDTT_documentation/master/
   $ git commit -m "My latest commit" .
   $ git push -u origin master
   $ bundle exec rake book:build_html

5. Now copy any new image files to the /images folder in the gh-pages branch (you will need to git add them), and rename LSDTT_book.html to index.html and copy to the gh-pages folder.

   $ pwd
   my/path/to/repo/LSDTT_documentation/gh-pages/
   $ cd images
   $ git add <filenames of new images>
   $ cd ..
   $ git commit "updating website" .

6. Now push the changes to the gh-pages branch

   $ bundle exec rake book:build_html
   $ pwd
   my/path/to/repo/LSDTT_documentation/gh-pages/
   $ git push -u origin gh-pages