Skip to content

Commit 2e5a51f

Browse files
simon-m-muddsimon-m-mudd
committed
Added the initial version of the documentation
0 parents  commit 2e5a51f

File tree

14 files changed

+1776
-0
lines changed

14 files changed

+1776
-0
lines changed

‎Gemfile

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
source 'https://rubygems.org'
2+
3+
gem 'rake'
4+
gem 'asciidoctor', '1.5.0'
5+
6+
gem 'json'
7+
gem 'awesome_print'
8+
9+
gem 'asciidoctor-epub3', '1.0.0.alpha.2'
10+
gem 'asciidoctor-pdf', '1.5.0.alpha.5'
11+
12+
gem 'coderay'
13+
gem 'pygments.rb'
14+
gem 'thread_safe'
15+
gem 'epubcheck'

‎LSDTT_PythonDocs.asc

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
= Reproducible plots of topographic analyses using LSDTopoTools and python
2+
Simon M Mudd
3+
:doctype: book
4+
:toc: left
5+
:icons: font
6+
:toclevels: 3
7+
:stem: latexmath
8+
9+
include::book/preface.asc[]
10+
11+
include::book/01-introduction/1-introduction.asc[]
12+
13+
include::book/02-Setting-up-python/Setting-up-python.asc[]
14+
15+
include::book/03-Getting-our-plotting-scripts/Getting-our-plotting-scripts.asc[]
16+
17+
include::book/03-Plotting-simple-rasters/Plotting-simple-rasters.asc[]

‎README.asc

+213
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
:numbered:
2+
3+
= A book template
4+
5+
This is a template for a book or website written with http://asciidoctor.org/[asciidoctor]. The resulting template website looks like this: http://simon-m-mudd.github.io/Book_template/. If you want to make your own website or book just clone this repository.
6+
You will meed to install https://www.ruby-lang.org/en/[ruby], https://rubygems.org/[rubygems] and http://bundler.io/[bundler] to get it working.
7+
8+
Install the ruby package `bundler` using
9+
10+
[source,console]
11+
----
12+
$ gem install bundler
13+
----
14+
15+
== Turning these files into pdf or html
16+
17+
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.
18+
19+
We will use http://bundler.io/[bundler], which manages http://asciidoctor.org/[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 https://www.ruby-lang.org/en/[ruby], https://rubygems.org/[rubygems] and http://bundler.io/[bundler] and then clone this repository into the directory of your choice from Github.
20+
21+
Once you have bundler installed, you can build the book with:
22+
23+
[source,console]
24+
----
25+
$ bundler install
26+
$ bundle exec rake book:build
27+
----
28+
29+
This will build *html* and *pdf* versions of the book.
30+
31+
You can also build an html only version:
32+
33+
[source,console]
34+
----
35+
$ bundler install
36+
$ bundle exec rake book:build_html
37+
----
38+
39+
WARNING: The build process will make a folder called `images` in the root directory,
40+
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.
41+
42+
=== Quick build asciidoctor (i.e., not using bundler)
43+
44+
You can also quickly generate the document by installing http://asciidoctor.org/[asciidoctor], and then running it on the `LSDTT_Book.asc` file:
45+
46+
[source,console]
47+
----
48+
$ gem install asciidoctor
49+
$ asciidoctor Book_template_top.asc
50+
----
51+
52+
WARNING: This quick generation will give you the text and cross-linking, but the images will not be linked.
53+
For images to be properly linked you need to run `bundle exec` (see above).
54+
55+
56+
== If you want to set up your own book, and have an associated website on github.io
57+
58+
. The point of this template is to allow you to build a nice book that is easily converted to html. One nice place to host this website is https://github.com/[github]. These are instructions for starting your own book using the template, and setting it up as a github.io website.
59+
. The first thing you need to do is make a directory for your very own book. Lets call it `MyBook`. Go into `MyBook` and clone this template into a directory called master:
60+
+
61+
[source,console]
62+
----
63+
$ mkdir MyBook
64+
$ cd MyBook
65+
$ git clone https://github.com/simon-m-mudd/Book_template.git master
66+
----
67+
+
68+
. Next, **delete** the `.git` directory inside the `master` directory.
69+
. At this point you might want to rename some of the files and folders to suit your new book or website. If you forget to do this you can always change the names of files and directories by using the `git mv` command.
70+
. Now use `git init` to start a new repository and then add and commit the files.
71+
+
72+
[source,console]
73+
----
74+
$ cd master
75+
$ git init
76+
$ git add .
77+
$ git commit -m "Added the files" .
78+
----
79+
+
80+
. Now start a new repository on github **without a readme**.
81+
. It will give you the remote name. Add it to the repository:
82+
+
83+
[source,console]
84+
----
85+
$ git remote add origin https://github.com/MYUSERNAME/MYREPONAME.git
86+
$ git push origin master
87+
----
88+
+
89+
You will need to replace `MYUSERNAME` and `MYREPONAME` with the appropraite names.
90+
+
91+
. Refresh the github repository page. You should see all the files from the template.
92+
. Now on the repository page, look above the files: you should see a tab for "Branches".
93+
Click on this and make a new branch called `gh-pages`.
94+
+ Now go back into your terminal window, go down a level using `cd ..`, and clone the **gh-pages** branch.
95+
+
96+
[source, console]
97+
----
98+
$ cd ..
99+
$ git clone https://github.com/MYUSERNAME/MYREPONAME.git gh-pages
100+
----
101+
+
102+
. Go into the gh-pages directory, check out the gh-pages branch, and delete the master branch (it will only delete the master branch form this directory).
103+
+
104+
[source, console]
105+
----
106+
$ cd gh-pages
107+
$ git checkout origin/gh-pages -b gh-pages
108+
$ git branch -d master
109+
----
110+
. You gh-pages branch is still full of rubbish you don't need. Remove it all. Then make a dummy index page.
111+
+
112+
[source, console]
113+
----
114+
$ git rm -rf .
115+
$ echo "My Page" > index.html
116+
$ git add index.html
117+
$ git commit -m "Added the index" .
118+
$ git push origin gh-pages
119+
----
120+
+
121+
. Go back to the *master* folder and build the book:
122+
+
123+
[source, console]
124+
----
125+
$ cd ..
126+
$ cd master
127+
$ bundle exec rake book:build_html
128+
----
129+
+
130+
WARNING: If you are on Windows and using *git bash*, it will not recognise Ruby commands, so you will need to open a separate powershell window to run the *bundle* command. This should not be a problem on Linux and MacOS.
131+
+
132+
. This will create a directory called *images* and an html file called *My_book.html*.
133+
+
134+
. Rename *My_book.html* to *index.html* and copy it as well as the *images* directory into the *gh-pages* directory.
135+
+
136+
. Now go back into the *gh-pages* directory, add the *images* directory, and then `commit` and `push` the changes (the below commands assume you are sitting in the `master` directory):
137+
+
138+
[source, console]
139+
----
140+
$ cd ..
141+
$ cd gh-pages
142+
$ git add images
143+
$ git commit -m "Updated the website" .
144+
$ git push origin gh-pages
145+
----
146+
+
147+
IMPORTANT: You **MUST** push to the **gh-pages** branch!! When you work in the **master** directory you `push` and `pull` to the **master** branch, and when you work in the **gh-pages** folder you `push` and `pull` from the **gh-pages** branch! If you mess this up you might have some painful cleaning up to do.
148+
+
149+
. Okay, you should now be able to look at your website on: http://MYUSERNAME.github.io/MYREPONAME, where `MYUSERNAME` is your github username and `MYREPONAME` is the name of the repo in which you stored your new book.
150+
151+
152+
== If you are making changes to this template
153+
154+
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.
155+
156+
I do not want any messy merging conflicts! To avoid this please keep the *master* and *gh-pages* separate on your computer!
157+
158+
. When checking out the code, check them out into two directories:
159+
+
160+
[source, console]
161+
----
162+
$ git clone https://github.com/simon-m-mudd/book_template.git master
163+
$ git clone https://github.com/simon-m-mudd/book_template.git gh-pages
164+
----
165+
+
166+
. In the gh-pages directory, check out the gh-pages branch and get rid of the master branch:
167+
+
168+
[source, console]
169+
----
170+
$ cd gh-pages
171+
$ git checkout origin/gh-pages -b gh-pages
172+
$ git branch -d master
173+
----
174+
+
175+
. Now, go back to the master branch, you can make changes there.
176+
177+
. When you commit changes to the master branch and you want to update the website, commit and push changes, then run bundle:
178+
+
179+
[source, console]
180+
----
181+
$ pwd
182+
my/path/to/repo/book_template/master/
183+
$ git commit -m "My latest commit" .
184+
$ git push -u origin master
185+
$ bundle exec rake book:build_html
186+
----
187+
+
188+
. Now copy any new image files to the /images folder in the gh-pages branch (you will need to git add them),
189+
and rename *My_book.html* to *index.html* and copy to the gh-pages folder.
190+
+
191+
[source, console]
192+
----
193+
$ pwd
194+
my/path/to/repo/book_template/gh-pages/
195+
$ cd images
196+
$ git add <filenames of new images>
197+
$ cd ..
198+
$ git commit "updating website" .
199+
----
200+
+
201+
. Now push the changes to the gh-pages branch
202+
+
203+
[source, console]
204+
----
205+
$ bundle exec rake book:build_html
206+
----
207+
+
208+
[source, console]
209+
----
210+
$ pwd
211+
my/path/to/repo/book_template/gh-pages/
212+
$ git push -u origin gh-pages
213+
----

‎Rakefile

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
namespace :book do
2+
desc 'prepare build'
3+
task :prebuild do
4+
Dir.mkdir 'images' unless Dir.exists? 'images'
5+
Dir.glob("book/*/images/*").each do |image|
6+
FileUtils.copy(image, "images/" + File.basename(image))
7+
end
8+
end
9+
10+
desc 'build basic book formats'
11+
task :build => :prebuild do
12+
puts "Converting to HTML..."
13+
`bundle exec asciidoctor LSDTT_PythonDocs.asc -o LSDTT_PythonDocs.html`
14+
puts " -- HTML output at LSDTT_PythonDocs.html"
15+
16+
puts "Converting to PDF... (this one takes a while)"
17+
`bundle exec asciidoctor-pdf LSDTT_PythonDocs.asc -o LSDTT_PythonDocs.pdf`
18+
puts " -- PDF output at LSDTT_PythonDocs.pdf"
19+
end
20+
21+
desc 'build html book formats'
22+
task :build_html => :prebuild do
23+
puts "Converting to HTML..."
24+
`bundle exec asciidoctor LSDTT_PythonDocs.asc -o LSDTT_PythonDocs.html`
25+
puts " -- HTML output at LSDTT_PythonDocs.html"
26+
end
27+
28+
desc 'build html with github stylesheet'
29+
task :build_html_gitcss => :prebuild do
30+
puts "Converting to HTML with github stylesheet..."
31+
`bundle exec asciidoctor LSDTT_PythonDocs.asc -a stylesheet=github.css -a stylesdir=./stylesheets -o My_book_github_style.html`
32+
puts " -- HTML output at My_book_github_style.html"
33+
end
34+
35+
end
36+
37+
task :default => "book:build"

‎book/01-introduction/1-introduction.asc

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:numbered:
2+
3+
4+
== Background and Motivation
5+
6+
This documentation describes plotting scripts, written in https://www.python.org/[python] that are used to plot output from http://lsdtopotools.github.io/[LSDTopoTools]. If you are looking for inforamtion on how to use *LSDTopoTools*, see our https://lsdtopotools.github.io/LSDTopoTools_workshop/[workshop documentation] or our http://lsdtopotools.github.io/LSDTT_book/[full documentation].
7+
8+
The output from http://lsdtopotools.github.io/[LSDTopoTools] is compatible with GIS software, so why would we write plotting scripts? The reason is that we want plotting tools that are totally reproducible: if you use our data and scripts you can get exactly the same figures that we get. Our objective is for anyone who reads our papers to be able to produce the exact same publication-ready figures that we had in the paper.
9+
10+
In addition, it can be very annoying to import layers into a GIS repeatedly and have to click loads of buttons selecting formatting, colour schemes, transparancies, etc. These scripts automate that process so you don't have to do a bunch of clicking.
11+
12+
We aim to use these scripts to compress our workflows, and hope that other users will benefit. One example is our http://onlinelibrary.wiley.com/doi/10.1002/2013JF002981/abstract[chi mapping] methods: in 2014 it took several weeks of concerted effort to get chi maps at a landscape scale and turn them into publication-ready figures. That process now takes a few hours thanks to these scripts.
13+
14+
Our scripts have seen much less development than our acutal analysis code (that is *LSDTopoTools*) and this documentation reflects the fact that these tools are incomplete. However, if you are a user of *LSDTopoTools* you can keep checking back and hopefully this documentation will grow through time,
15+

‎book/02-Setting-up-python/Setting-up-python.asc

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
== Setting up Python
3+
4+
https://www.python.org/[Python] is an open source programming language popular with scientists and engineers. You will need to both set up python and install the appropriate packages for our scripts to work. To do this, we use http://conda.pydata.org/miniconda.html[Miniconda], which works on all common operating systems (Linux, Windows and MacOS) and makes installation and updates of python packages very simple.
5+
6+
include::sections/conda-installation.asc[]
7+
8+
include::sections/our-plotting-functions.asc[]

‎book/02-Setting-up-python/sections/conda-installation.asc

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
=== Setting up Python with Miniconda
2+
3+
Hopefully this will be both simple and painless. You will need to be connected to the internet.
4+
5+
. Download and install the **python 2.7** version of http://conda.pydata.org/miniconda.html[Miniconda] for your operating system.
6+
+
7+
IMPORTANT: You *MUST* use python 2.7 because our scripts use a package called https://pypi.python.org/pypi/GDAL/[GDAL] that is not compatible with python 3!
8+
+
9+
. Once you have installed miniconda, you can go into a powershell (windows) or terminal (MacOS and Linux) and get the other stuff you need:
10+
+
11+
[source,consol]
12+
----
13+
PS> conda install scipy
14+
PS> conda install matplotlib
15+
PS> conda install pandas
16+
PS> conda install gdal
17+
PS> conda install spyder
18+
----
19+
+
20+
. To run Spyder you just type `spyder` at the command line.
21+
+
22+
WARNING: Spyder needs an older version of a package called *PyQt*. If spyder doesn't start correctly, run `conda install pyqt=4.10 -f`
23+
+
24+
WARNING: For Spyder to work you will need a windowing system so you cannot run it through a text-only server. That means if you are using a https://lsdtopotools.github.io/LSDTopoTools_workshop/#_starting_up_on_a_non_linux_operating_system_windows_macos[vagrant machine] you should install pyhton on your host computer and not on the vagrant machine.
25+
+
26+
. Everything should be set up. Yay!!

‎book/03-Getting-our-plotting-scripts/Getting-our-plotting-scripts.asc

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
== Getting our plotting scripts
2+
3+
Use git!
4+
5+
=== Why not put a summary here?
6+

‎book/04-Plotting-simple-rasters/Plotting-simple-rasters.asc

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
== A chapter
2+
3+
Here is another chapter. You can add sections using the include links.
4+
5+
include::sections/A-chapter-section.asc[]
6+
7+
include::sections/More-advanced.asc[]
8+
9+
=== Why not put a summary here?
10+

‎book/index.asc

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
== Index

‎book/preface.asc

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
2+
3+
[preface]
4+
== Preface by Simon M. Mudd
5+
6+
This describes some of the python scripts for plotting analyses from http://lsdtopotools.github.io/[LSDTopoTools].

‎book/toc.asc

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{ toc }}

0 commit comments

Comments
 (0)