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/
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.
1. Getting asciidoctor to work
Please read our instructions on getting asciidoctor to work: https://lsdtopotools.github.io/LSDTT_documentation/LSDTT_building_documentation.html
2. 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.
3. 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
gh-pages branches. To properly clone the repository
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
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.
When you commit changes to the master branch and you want to update the website, commit and push changes, then run
$ 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
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" .
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