The master documentation for LSDTopoTools
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
LSDTT_BasinwideCRN
LSDTT_MuddPILE
LSDTT_QGIS
LSDTT_advanced_workshop
LSDTT_automation
LSDTT_basic_usage
LSDTT_building_documentation
LSDTT_channel_extraction
LSDTT_chi_analysis
LSDTT_floodplains_terraces
LSDTT_general_overview
LSDTT_hillslope_metrics
LSDTT_installation
LSDTT_introduction_to_geospatial_data
LSDTT_knickpoint_analysis
LSDTT_main_page
LSDTT_open_source_software
LSDTT_troubleshooting
LSDTT_using_linux
LSDTT_visualisation
html_build
README.asc
compile_LSDTTDocs.py
dockerfile

README.asc

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/

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.

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