Documentation for plotting routines written in python for LSDTopoTools

If you just want the documentation go here: Python doc website. The below instructions are for updating the docs and building the website.

You will meed to install ruby, rubygems and bundler to get it working.

Install the ruby package bundler using

$ gem install bundler

1. Turning these files into pdf or html

Note	If you want to set up your own book and website, skip to the next section. These instructions are just for turning the template into pdf and html files.

We will use bundler, which manages asciidoctor and a a bunch of other stuff, to turn these files into pdf and html. The template files do this work for you so all you need to do to egt started is install ruby, rubygems and bundler and then clone this repository into the directory of your choice from Github.

Once you have bundler installed, you can build the book with:

$ bundler install
$ bundle exec rake book:build

This will build html and pdf versions of the book.

You can also build an html only version:

$ bundler install
$ bundle exec rake book:build_html

Warning

The build process will make a folder called images in the root directory, which on some systems must be deleted before new builds. This is a particular problem on Windows systems, where sometimes windows will stupidly not let you delete the thumbs.db file it automatically generates. To get around this, right click on the images directory and unselect read only, then you should be able to delete the folder. In general, however, as long as you do not look in the images directory you will not have this problem.

2. If you are making changes to this template

Note	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!

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

   $ git clone https://github.com/LSDtopotools/LSDTT_PythonDocs.git master
   $ git clone https://github.com/LSDtopotools/LSDTT_PythonDocs.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/website/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_PythonDocs.html to index.html and copy to the gh-pages folder.

   $ pwd
   my/path/to/website/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/website/gh-pages/
   $ git push -u origin gh-pages