├── gh-publisher-scripts
    ├── build.sh
    ├── example.travis.yml
    ├── javascripts
    │   └── scale.fix.js
    ├── copy.sh
    ├── README.md
    ├── front-matter.yml
    ├── index.html
    ├── gh-publisher.sh
    └── stylesheets
    │   ├── pygment_trac.css
    │   └── styles.css
└── README.md


/gh-publisher-scripts/build.sh:
--------------------------------------------------------------------------------
 1 | #
 2 | # Use this file to configure your build.
 3 | #
 4 | # You have the following variables available:
 5 | #
 6 | # GH_PUBLISHER_PROJECT_DIR - The root of your project repository.
 7 | # GH_PUBLISHER_SCRIPTS_DIR - The gh-publisher-scripts directory.
 8 | #
 9 | # The current working directory is $GH_PUBLISHER_PROJECT_DIR.
10 | #
11 | 
12 | cd "$GH_PUBLISHER_PROJECT_DIR"
13 | make
14 | 


--------------------------------------------------------------------------------
/gh-publisher-scripts/example.travis.yml:
--------------------------------------------------------------------------------
 1 | language: ruby
 2 | rvm:
 3 | - 1.9.3
 4 | script: /bin/bash gh-publisher-scripts/gh-publisher.sh
 5 | before_install:
 6 | - yes "" | sudo apt-add-repository ppa:texlive-backports/ppa
 7 | - sudo apt-get update -y
 8 | - sudo apt-get install -y
 9 |      inkscape
10 |      texlive-fonts-recommended
11 |      texlive-latex-extra
12 |      texlive-latex-recommended
13 |      texlive-xetex
14 | 


--------------------------------------------------------------------------------
/gh-publisher-scripts/javascripts/scale.fix.js:
--------------------------------------------------------------------------------
 1 | var metas = document.getElementsByTagName('meta');
 2 | var i;
 3 | if (navigator.userAgent.match(/iPhone/i)) {
 4 |   for (i=0; i<metas.length; i++) {
 5 |     if (metas[i].name == "viewport") {
 6 |       metas[i].content = "width=device-width, minimum-scale=1.0, maximum-scale=1.0";
 7 |     }
 8 |   }
 9 |   document.addEventListener("gesturestart", gestureStart, false);
10 | }
11 | function gestureStart() {
12 |   for (i=0; i<metas.length; i++) {
13 |     if (metas[i].name == "viewport") {
14 |       metas[i].content = "width=device-width, minimum-scale=0.25, maximum-scale=1.6";
15 |     }
16 |   }
17 | }


--------------------------------------------------------------------------------
/gh-publisher-scripts/copy.sh:
--------------------------------------------------------------------------------
 1 | #
 2 | # Use this file to configure whichever artifacts you wish to publish.
 3 | #
 4 | # You have the following variables available:
 5 | #
 6 | # GH_PUBLISHER_PROJECT_DIR - The root of your project repository.
 7 | # GH_PUBLISHER_PUBLISH_DIR - The destination for files to be published.
 8 | # GH_PUBLISHER_SCRIPTS_DIR - The gh-publisher-scripts directory.
 9 | #
10 | # The current working directory is $GH_PUBLISHER_PROJECT_DIR.
11 | #
12 | 
13 | find . \( \
14 |      -name \*.html -o \
15 |      -name \*.css -o \
16 |      -name \*.js -o \
17 |      -name \*.gif -o \
18 |      -name \*.jpeg -o \
19 |      -name \*.jpg -o \
20 |      -name \*.png -o \
21 |      -name \*.pdf \
22 |      \) -print0 |
23 |     rsync -av --files-from=- --from0 ./ "$GH_PUBLISHER_PUBLISH_DIR"
24 | 


--------------------------------------------------------------------------------
/gh-publisher-scripts/README.md:
--------------------------------------------------------------------------------
 1 | gh-publisher
 2 | ============
 3 | 
 4 | This is a small package of software which will help you configure an
 5 | automated build and publish process, using Travis CI and GitHub Pages.
 6 | 
 7 | See https://github.com/ewanmellor/gh-publisher for more details.
 8 | 
 9 | 
10 | License
11 | -------
12 | 
13 | index.html, scale.fix.js, pygment_trac.css, styles.css: these are modified
14 | versions of https://github.com/orderedlist/minimal, which is licensed under a
15 | Creative Commons Attribution-ShareAlike 3.0 Unported License.
16 | http://creativecommons.org/licenses/by-sa/3.0/.
17 | 
18 | The remaining files in this repository are by Ewan Mellor, and are dedicated
19 | to the public domain.
20 | To the extent possible under law, Ewan Mellor has waived all copyright and
21 | related or neighboring rights to this work.
22 | http://creativecommons.org/publicdomain/zero/1.0/.
23 | 


--------------------------------------------------------------------------------
/gh-publisher-scripts/front-matter.yml:
--------------------------------------------------------------------------------
 1 | #
 2 | # This file controls the details on the published HTML page.
 3 | #
 4 | # All the values here are optional, but it will obviously look a lot
 5 | # better if you fill them in.
 6 | #
 7 | # Remove the # from the front of each line, and then edit appropriately.
 8 | #
 9 | 
10 | #title:
11 | #abstract:
12 | 
13 | # This controls which file is shown on the right-hand side of the published
14 | # HTML page.  By default it will take the first PDF or HTML file that it
15 | # finds.  If that doesn't work for you, you can specify the correct file here.
16 | #iframe_src: book.pdf
17 | 
18 | # You can specify multiple authors, just follow the pattern below.
19 | # These fields can contain HTML tags.  You probably want to put <br />
20 | # in the address somewhere, indicating a line break.
21 | 
22 | #authors:
23 | #- name: Joseph H. Bloggs
24 | #  address: International Institute for Interminable Examples, P.O. Box 1,<br />Beverly Hills, CA 90210, USA.
25 | #- name: Clara McNarma
26 | #  address: School of Dance and Drama,<br />College of the Northern Light,<br />Dogger, Fisher, German Bight.
27 | 


--------------------------------------------------------------------------------
/gh-publisher-scripts/index.html:
--------------------------------------------------------------------------------
 1 | ---
 2 | layout: default
 3 | ---
 4 | 
 5 | <!doctype html>
 6 | <html>
 7 |   <head>
 8 |     <meta charset="utf-8">
 9 |     <meta http-equiv="X-UA-Compatible" content="chrome=1">
10 |     <title>{{ site.title }}</title>
11 | 
12 |     <link rel="stylesheet" href="stylesheets/styles.css">
13 |     <link rel="stylesheet" href="stylesheets/pygment_trac.css">
14 |     <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
15 |     <!--[if lt IE 9]>
16 |     <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
17 |     <![endif]-->
18 |   </head>
19 |   <body>
20 |     <div class="wrapper">
21 |       <header>
22 |         <h1>{{site.title }}</h1>
23 | {% for author in site.authors %}
24 | 
25 | <p>{{ author.name }}<br />
26 | <em>{{ author.address }}</em></p>
27 | 
28 | {% endfor %}
29 | 
30 | {% if site.abstract %}
31 |       <p>{{ site.abstract }}</p>
32 | {% endif %}
33 | 
34 |         <p class="view"><a href="https://github.com/{{ site.github_username }}/{{ site.github_repo }}">View the Project on GitHub <small>{{ site.github_username }}/{{ site.github_repo }}</small></a></p>
35 | 
36 |         <ul>
37 |           <li><a href="https://github.com/{{ site.github_username }}/{{ site.github_repo }}/issues">Send feedback</a></li>
38 |         </ul>
39 |       </header>
40 | {% if site.iframe_src %}
41 |       <section>
42 | <iframe src="{{ site.iframe_src }}" />
43 |       </section>
44 | {% endif %}
45 |     </div>
46 |     <script src="javascripts/scale.fix.js"></script>
47 |   </body>
48 | </html>
49 | 


--------------------------------------------------------------------------------
/gh-publisher-scripts/gh-publisher.sh:
--------------------------------------------------------------------------------
  1 | #!/bin/bash
  2 | 
  3 | set -eu
  4 | 
  5 | function readlink_f() {
  6 |   if [ $(uname) = 'Darwin' ]
  7 |   then
  8 |     DIR=$(echo "${1%/*}")
  9 |     FILE=$(basename "$1")
 10 |     (cd "$DIR" && echo "$(pwd -P)/$FILE")
 11 |   else
 12 |     readlink -f "$1"
 13 |   fi
 14 | }
 15 | 
 16 | gh_token="${GH_TOKEN-}"
 17 | git_name="${GIT_NAME-Automated build by gh-publisher}"
 18 | git_email="${GIT_EMAIL-not.a.real.person@example.com}"
 19 | git_remote="${GIT_REMOTE-origin}"
 20 | git_publish_branch="${GIT_PUBLISH_BRANCH-gh-pages}"
 21 | 
 22 | if [ -z "$gh_token" ]
 23 | then
 24 |   echo "GH_TOKEN is not set.  Cannot proceed." >&2
 25 |   echo "Please see the installation instructions." >&2
 26 |   exit 1
 27 | fi
 28 | 
 29 | scripts_dir=$(dirname $(readlink_f "$0"))
 30 | scripts_dir_name=$(basename "$scripts_dir")
 31 | project_dir=$(dirname "$scripts_dir")
 32 | 
 33 | cd "$scripts_dir"
 34 | git_url=$(git config "remote.${git_remote}.url" |
 35 |           sed -e 's,git://*,https://,' -e "s,https://,https://${gh_token}@,")
 36 | git_rev=$(git rev-parse HEAD)
 37 | github_username=$(echo "$git_url" | sed -e 's,^https://[^/]*/\([^/]*\)/.*$,\1,')
 38 | github_repo=$(echo "$git_url" | sed -e 's,^https://[^/]*/[^/]*/\([^/.]*\).*$,\1,')
 39 | 
 40 | tmpdir=$(mktemp -t publish.XXXXXX -d)
 41 | (cd "$tmpdir"
 42 |  git clone "$git_url" "publish"
 43 |  cd publish
 44 |  git config user.name "$git_name"
 45 |  git config user.email "$git_email"
 46 |  if git branch -av | grep -q "remotes/origin/$git_publish_branch"
 47 |  then
 48 |    git checkout "$git_publish_branch"
 49 |  else
 50 |    git checkout --orphan "$git_publish_branch"
 51 |    git reset .
 52 |    git clean -dfx
 53 |  fi
 54 | )
 55 | publish_dir="$tmpdir/publish"
 56 | 
 57 | export GH_PUBLISHER_PROJECT_DIR="$project_dir"
 58 | export GH_PUBLISHER_PUBLISH_DIR="$publish_dir"
 59 | export GH_PUBLISHER_SCRIPTS_DIR="$scripts_dir"
 60 | 
 61 | (cd "$project_dir" && /bin/bash "$scripts_dir/build.sh")
 62 | (cd "$project_dir" && /bin/bash "$scripts_dir/copy.sh")
 63 | 
 64 | published_scripts="$publish_dir/$scripts_dir_name"
 65 | if [ -d "$published_scripts" ]
 66 | then
 67 |   rsync -av "$published_scripts"/* "$publish_dir"
 68 |   rm -rf "$published_scripts"
 69 | fi
 70 | 
 71 | config_yml="$publish_dir/_config.yml"
 72 | cp "$scripts_dir/front-matter.yml" "$config_yml"
 73 | echo "github_username: $github_username" >>"$config_yml"
 74 | echo "github_repo: $github_repo" >>"$config_yml"
 75 | if ! grep -q "^iframe_src:" "$config_yml"
 76 | then
 77 |   iframe_src=$( (cd "$publish_dir"; ls *.pdf || true) | sort | head -n1)
 78 |   if [ -z "$iframe_src" ]
 79 |   then
 80 |     iframe_src=$( (cd "$publish_dir"; ls *.html || true) | sort | head -n1)
 81 |   fi
 82 |   if [ -n "$iframe_src" ]
 83 |   then
 84 |     echo "iframe_src: $iframe_src" >>"$config_yml"
 85 |   fi
 86 | fi
 87 | if ! grep -q "^title:" "$config_yml"
 88 | then
 89 |   echo "title: $github_repo" >>"$config_yml"
 90 | fi
 91 | 
 92 | (cd "$publish_dir"
 93 |  git add -A
 94 |  if ! git diff --quiet --staged
 95 |  then
 96 |    git commit -m "Built from revision $git_rev."
 97 |    git push -q origin "$git_publish_branch:$git_publish_branch"
 98 |  else
 99 |    echo "Nothing has changed!  I hope that's what you expected." >&2
100 |  fi
101 | )
102 | 


--------------------------------------------------------------------------------
/gh-publisher-scripts/stylesheets/pygment_trac.css:
--------------------------------------------------------------------------------
 1 | .highlight  { background: #ffffff; }
 2 | .highlight .c { color: #999988; font-style: italic } /* Comment */
 3 | .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
 4 | .highlight .k { font-weight: bold } /* Keyword */
 5 | .highlight .o { font-weight: bold } /* Operator */
 6 | .highlight .cm { color: #999988; font-style: italic } /* Comment.Multiline */
 7 | .highlight .cp { color: #999999; font-weight: bold } /* Comment.Preproc */
 8 | .highlight .c1 { color: #999988; font-style: italic } /* Comment.Single */
 9 | .highlight .cs { color: #999999; font-weight: bold; font-style: italic } /* Comment.Special */
10 | .highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
11 | .highlight .gd .x { color: #000000; background-color: #ffaaaa } /* Generic.Deleted.Specific */
12 | .highlight .ge { font-style: italic } /* Generic.Emph */
13 | .highlight .gr { color: #aa0000 } /* Generic.Error */
14 | .highlight .gh { color: #999999 } /* Generic.Heading */
15 | .highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
16 | .highlight .gi .x { color: #000000; background-color: #aaffaa } /* Generic.Inserted.Specific */
17 | .highlight .go { color: #888888 } /* Generic.Output */
18 | .highlight .gp { color: #555555 } /* Generic.Prompt */
19 | .highlight .gs { font-weight: bold } /* Generic.Strong */
20 | .highlight .gu { color: #800080; font-weight: bold; } /* Generic.Subheading */
21 | .highlight .gt { color: #aa0000 } /* Generic.Traceback */
22 | .highlight .kc { font-weight: bold } /* Keyword.Constant */
23 | .highlight .kd { font-weight: bold } /* Keyword.Declaration */
24 | .highlight .kn { font-weight: bold } /* Keyword.Namespace */
25 | .highlight .kp { font-weight: bold } /* Keyword.Pseudo */
26 | .highlight .kr { font-weight: bold } /* Keyword.Reserved */
27 | .highlight .kt { color: #445588; font-weight: bold } /* Keyword.Type */
28 | .highlight .m { color: #009999 } /* Literal.Number */
29 | .highlight .s { color: #d14 } /* Literal.String */
30 | .highlight .na { color: #008080 } /* Name.Attribute */
31 | .highlight .nb { color: #0086B3 } /* Name.Builtin */
32 | .highlight .nc { color: #445588; font-weight: bold } /* Name.Class */
33 | .highlight .no { color: #008080 } /* Name.Constant */
34 | .highlight .ni { color: #800080 } /* Name.Entity */
35 | .highlight .ne { color: #990000; font-weight: bold } /* Name.Exception */
36 | .highlight .nf { color: #990000; font-weight: bold } /* Name.Function */
37 | .highlight .nn { color: #555555 } /* Name.Namespace */
38 | .highlight .nt { color: #000080 } /* Name.Tag */
39 | .highlight .nv { color: #008080 } /* Name.Variable */
40 | .highlight .ow { font-weight: bold } /* Operator.Word */
41 | .highlight .w { color: #bbbbbb } /* Text.Whitespace */
42 | .highlight .mf { color: #009999 } /* Literal.Number.Float */
43 | .highlight .mh { color: #009999 } /* Literal.Number.Hex */
44 | .highlight .mi { color: #009999 } /* Literal.Number.Integer */
45 | .highlight .mo { color: #009999 } /* Literal.Number.Oct */
46 | .highlight .sb { color: #d14 } /* Literal.String.Backtick */
47 | .highlight .sc { color: #d14 } /* Literal.String.Char */
48 | .highlight .sd { color: #d14 } /* Literal.String.Doc */
49 | .highlight .s2 { color: #d14 } /* Literal.String.Double */
50 | .highlight .se { color: #d14 } /* Literal.String.Escape */
51 | .highlight .sh { color: #d14 } /* Literal.String.Heredoc */
52 | .highlight .si { color: #d14 } /* Literal.String.Interpol */
53 | .highlight .sx { color: #d14 } /* Literal.String.Other */
54 | .highlight .sr { color: #009926 } /* Literal.String.Regex */
55 | .highlight .s1 { color: #d14 } /* Literal.String.Single */
56 | .highlight .ss { color: #990073 } /* Literal.String.Symbol */
57 | .highlight .bp { color: #999999 } /* Name.Builtin.Pseudo */
58 | .highlight .vc { color: #008080 } /* Name.Variable.Class */
59 | .highlight .vg { color: #008080 } /* Name.Variable.Global */
60 | .highlight .vi { color: #008080 } /* Name.Variable.Instance */
61 | .highlight .il { color: #009999 } /* Literal.Number.Integer.Long */
62 | 
63 | .type-csharp .highlight .k { color: #0000FF }
64 | .type-csharp .highlight .kt { color: #0000FF }
65 | .type-csharp .highlight .nf { color: #000000; font-weight: normal }
66 | .type-csharp .highlight .nc { color: #2B91AF }
67 | .type-csharp .highlight .nn { color: #000000 }
68 | .type-csharp .highlight .s { color: #A31515 }
69 | .type-csharp .highlight .sc { color: #A31515 }
70 | 


--------------------------------------------------------------------------------
/gh-publisher-scripts/stylesheets/styles.css:
--------------------------------------------------------------------------------
  1 | @import url(https://fonts.googleapis.com/css?family=Lato:300italic,700italic,300,700);
  2 | 
  3 | body {
  4 |   padding:50px;
  5 |   font:14px/1.5 Lato, "Helvetica Neue", Helvetica, Arial, sans-serif;
  6 |   color:#777;
  7 |   font-weight:300;
  8 | }
  9 | 
 10 | h1, h2, h3, h4, h5, h6 {
 11 |   color:#222;
 12 |   margin:0 0 20px;
 13 | }
 14 | 
 15 | p, ul, ol, table, pre, dl {
 16 |   margin:0 0 20px;
 17 | }
 18 | 
 19 | h1, h2, h3 {
 20 |   line-height:1.1;
 21 | }
 22 | 
 23 | h1 {
 24 |   font-size:28px;
 25 | }
 26 | 
 27 | h2 {
 28 |   color:#393939;
 29 | }
 30 | 
 31 | h3, h4, h5, h6 {
 32 |   color:#494949;
 33 | }
 34 | 
 35 | a {
 36 |   color:#39c;
 37 |   font-weight:400;
 38 |   text-decoration:none;
 39 | }
 40 | 
 41 | a small {
 42 |   font-size:11px;
 43 |   color:#777;
 44 |   margin-top:-0.6em;
 45 |   display:block;
 46 | }
 47 | 
 48 | .wrapper {
 49 |   width:860px;
 50 |   margin:0 auto;
 51 | }
 52 | 
 53 | blockquote {
 54 |   border-left:1px solid #e5e5e5;
 55 |   margin:0;
 56 |   padding:0 0 0 20px;
 57 |   font-style:italic;
 58 | }
 59 | 
 60 | code, pre {
 61 |   font-family:Monaco, Bitstream Vera Sans Mono, Lucida Console, Terminal;
 62 |   color:#333;
 63 |   font-size:12px;
 64 | }
 65 | 
 66 | pre {
 67 |   padding:8px 15px;
 68 |   background: #f8f8f8;  
 69 |   border-radius:5px;
 70 |   border:1px solid #e5e5e5;
 71 |   overflow-x: auto;
 72 | }
 73 | 
 74 | table {
 75 |   width:100%;
 76 |   border-collapse:collapse;
 77 | }
 78 | 
 79 | th, td {
 80 |   text-align:left;
 81 |   padding:5px 10px;
 82 |   border-bottom:1px solid #e5e5e5;
 83 | }
 84 | 
 85 | dt {
 86 |   color:#444;
 87 |   font-weight:700;
 88 | }
 89 | 
 90 | th {
 91 |   color:#444;
 92 | }
 93 | 
 94 | img {
 95 |   max-width:100%;
 96 | }
 97 | 
 98 | header {
 99 |   width:270px;
100 |   float:left;
101 |   position:fixed;
102 | }
103 | 
104 | header ul {
105 |   list-style:none;
106 |   height:40px;
107 |   
108 |   padding:0;
109 |   
110 |   background: #eee;
111 |   background: -moz-linear-gradient(top, #f8f8f8 0%, #dddddd 100%);
112 |   background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#f8f8f8), color-stop(100%,#dddddd));
113 |   background: -webkit-linear-gradient(top, #f8f8f8 0%,#dddddd 100%);
114 |   background: -o-linear-gradient(top, #f8f8f8 0%,#dddddd 100%);
115 |   background: -ms-linear-gradient(top, #f8f8f8 0%,#dddddd 100%);
116 |   background: linear-gradient(top, #f8f8f8 0%,#dddddd 100%);
117 |   
118 |   border-radius:5px;
119 |   border:1px solid #d2d2d2;
120 |   box-shadow:inset #fff 0 1px 0, inset rgba(0,0,0,0.03) 0 -1px 0;
121 |   width:270px;
122 | }
123 | 
124 | header li {
125 |   height:40px;
126 | }
127 | 
128 | header ul a {
129 |   line-height:1;
130 |   font-size:24px;
131 |   color:#999;
132 |   display:block;
133 |   text-align:center;
134 |   padding-top:6px;
135 |   height:40px;
136 | }
137 | 
138 | strong {
139 |   color:#222;
140 |   font-weight:700;
141 | }
142 | 
143 | header ul a strong {
144 |   font-size:14px;
145 |   display:block;
146 |   color:#222;
147 | }
148 | 
149 | section {
150 |   width:500px;
151 |   height: 600px;
152 |   float:right;
153 |   padding-bottom:50px;
154 | }
155 | 
156 | section iframe {
157 |   width: 100%;
158 |   height: 600px;
159 | }
160 | 
161 | small {
162 |   font-size:11px;
163 | }
164 | 
165 | hr {
166 |   border:0;
167 |   background:#e5e5e5;
168 |   height:1px;
169 |   margin:0 0 20px;
170 | }
171 | 
172 | footer {
173 |   width:270px;
174 |   float:left;
175 |   position:fixed;
176 |   bottom:50px;
177 | }
178 | 
179 | @media print, screen and (max-width: 960px) {
180 |   
181 |   div.wrapper {
182 |     width:auto;
183 |     margin:0;
184 |   }
185 |   
186 |   header, section, footer {
187 |     float:none;
188 |     position:static;
189 |     width:auto;
190 |   }
191 |   
192 |   header {
193 |     padding-right:320px;
194 |   }
195 |   
196 |   section {
197 |     border:1px solid #e5e5e5;
198 |     border-width:1px 0;
199 |     padding:20px 0;
200 |     margin:0 0 20px;
201 |   }
202 |   
203 |   header a small {
204 |     display:inline;
205 |   }
206 |   
207 |   header ul {
208 |     position:absolute;
209 |     right:50px;
210 |     top:52px;
211 |   }
212 | }
213 | 
214 | @media print, screen and (max-width: 720px) {
215 |   body {
216 |     word-wrap:break-word;
217 |   }
218 |   
219 |   header {
220 |     padding:0;
221 |   }
222 |   
223 |   header ul, header p.view {
224 |     position:static;
225 |   }
226 |   
227 |   pre, code {
228 |     word-wrap:normal;
229 |   }
230 | }
231 | 
232 | @media print, screen and (max-width: 480px) {
233 |   body {
234 |     padding:15px;
235 |   }
236 |   
237 |   header ul {
238 |     display:none;
239 |   }
240 | }
241 | 
242 | @media print {
243 |   body {
244 |     padding:0.4in;
245 |     font-size:12pt;
246 |     color:#444;
247 |   }
248 | }
249 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | gh-publisher
  2 | ============
  3 | 
  4 | This is a small package of software which will help you configure an
  5 | automated build and publish process, using Travis CI and GitHub Pages.
  6 | 
  7 | gh-publisher was originally designed for academic and scientific papers
  8 | written in LaTeX.  Each change to the LaTeX triggers an automated build to
  9 | re-generate the PDF and then publish it.  You can easily extend gh-publisher
 10 | to perform different build processes, as described below.
 11 | 
 12 | The publishing template is also configured to receive feedback on your work
 13 | through GitHub Issues.
 14 | 
 15 | This is entirely dependent on GitHub and Travis CI.
 16 | 
 17 | [Example here.](http://drphilmarshall.github.io/Ideas-for-Citizen-Science-in-Astronomy/) Click through to the project on github to see the files in place. 
 18 | 
 19 | Installation
 20 | ------------
 21 | 
 22 | I assume that you have a git repository of your own, containing whatever
 23 | project it is that you want to build.  If you haven't already done so,
 24 | you need to host that repository on GitHub, and you need a local clone of it
 25 | on your machine.  If you don't know how to do that, see
 26 | https://help.github.com.
 27 | 
 28 | The instructions below use the following references.  Substitute the correct
 29 | value whenever you see one of these:
 30 | 
 31 | 1. `$PROJECT_DIR`: the directory containing your local clone of your project.
 32 | 2. `$GITHUB_USERNAME`: your GitHub username.
 33 | 3. `$REPO_NAME`: the name of your project's git repository.
 34 | 
 35 | ### Enable issue tracking on GitHub
 36 | 
 37 | 1. Visit your repository settings at
 38 | https://github.com/$GITHUB_USERNAME/$REPO_NAME/settings.
 39 | 2. In the Features section, ensure that Issues is checked.
 40 | 
 41 | ### Enable automated builds on Travis CI
 42 | 
 43 | 1. Sign in to Travis CI using your GitHub credentials at https://travis-ci.org.
 44 | 2. Visit your Travis CI profile page at
 45 | https://travis-ci.org/profile/$GITHUB_USERNAME.
 46 | 3. Click Sync now to refresh the list of repositories.
 47 | 3. Enable builds on your repository by flicking the appropriate switch.
 48 | 
 49 | ### Allow Travis CI to publish to GitHub Pages on your behalf
 50 | 
 51 | You need to generate a GitHub access token.  You are going to give this to
 52 | Travis CI, which will grant it access to publish on your behalf.
 53 | 
 54 | 1. Visit your GitHub application settings at
 55 | https://github.com/settings/applications.
 56 | 2. Under Personal access tokens, click "Generate new token".  GitHub will ask
 57 | for your password if you haven't entered it recently.
 58 | 3. Set the Token description to "Travis CI" (or whatever you want).
 59 | 4. Check "public_repo" as the scope, and uncheck all the other scopes.  This
 60 | limits Travis CI so that it is only able to publish to your public GitHub
 61 | repositories, and can't modify anything else.
 62 | 5. Click Generate token.
 63 | 6. You will see a new token -- a long string of numbers and letters.  Leave
 64 | this window open for now -- this is the only time that you will see this token.
 65 | 7. In a new window, visit
 66 | https://travis-ci.org/$GITHUB_USERNAME/$REPO_NAME/settings/env_vars.
 67 | 8. Click "Add a new variable".
 68 | 9. Set the Name to `GH_TOKEN`.
 69 | 10. Set the Value to that long string of numbers and letters in the other
 70 | window.
 71 | 11. Leave "Display value in build logs" turned off.
 72 | 12. Click "Add".
 73 | 13. You can close the window with your GitHub access token now, you're done.
 74 | 
 75 | ### Configure the name and email address used on git commits
 76 | 
 77 | You can optionally set the name and email address used on the git commits
 78 | when pages are published.  If you don't do this, they will come out as
 79 | `"Automated build by gh-publisher <not.a.real.person@example.com>"`.
 80 | 
 81 | 1. Visit https://travis-ci.org/$GITHUB_USERNAME/$REPO_NAME/settings/env_vars.
 82 | 2. Click "Add a new variable".
 83 | 3. Set the Name to `GIT_NAME`.
 84 | 4. Set the Value to `"<Your name> [automatic build]"`, or whatever you want.
 85 | 5. Click "Add".
 86 | 6. Repeat for `GIT_EMAIL`, also set to whatever you want.
 87 | 
 88 | ### Configure your project
 89 | 
 90 | 1. Copy the `gh-publisher-scripts` directory and all its contents from this
 91 | repository into `$PROJECT_DIR`.
 92 | 2. Copy `gh-publisher-scripts/example.travis.yml`, and place it in
 93 | `$PROJECT_DIR/.travis.yml`.  Note that the name of this file is critical:
 94 | it needs to be at the top level of your project, and it needs to be named
 95 | `.travis.yml` -- with a period at the front and no period at the end.
 96 | 3. If necessary, edit `gh-publisher-scripts/build.sh` and
 97 | `gh-publisher-scripts/copy.sh`.  By default, these are configured to
 98 | build the project by calling `make` at the top level, and then to copy
 99 | `*.pdf`, `*.html`, `*.css`, `*.js`, `*.png`, `*.jpeg`, `*.jpg`, `*.gif` for
100 | publication.  If you want to do something else, then you need to edit those
101 | files appropriately.
102 | 4. Commit the entire contents of `gh-publisher-scripts` and your new
103 | `.travis.yml` to your repository, and push to GitHub.
104 | 5. After a few minutes you should see your build begin, by looking at your
105 | status page on https://travis-ci.org.
106 | 
107 | ### Configure the front matter
108 | 
109 | You can optionally set the title and authors for the front section on the
110 | generated website.  If you don't do this, default values will be inserted,
111 | derived from the project details.  It will look a lot better if you set
112 | these values though.
113 | 
114 | 1. Edit `gh-publisher-scripts/front-matter.yml` to taste.
115 | 2. Commit the changes and push to GitHub.
116 | 
117 | ### Check that it's all worked
118 | 
119 | 1. Visit https://$GITHUB_USERNAME.github.io/$REPO_NAME/.  Hopefully you have
120 | a page here now!  This can take up to ten minutes to appear the first time
121 | (future builds are instant).
122 | 
123 | Configuring other kinds of builds
124 | ---------------------------------
125 | 
126 | The packages used for building are installed by `.travis.yml`.  You can edit
127 | the list at the end if you need other packages as part of your build.
128 | 
129 | You can also edit `gh-publisher-scripts/build.sh` and
130 | `gh-publisher-scripts/copy.sh` to change what is built and what is copied
131 | before it is published.
132 | 
133 | Acknowledgments
134 | ---------------
135 | 
136 | gh-publisher was inspired by Phil Marshall, as part of Science Hack Day
137 | San Francisco 2014.  https://github.com/drphilmarshall.
138 | http://sciencehackday.org.
139 | 
140 | The publishing template is derived from GitHub's automatic page generator,
141 | using the Minimal theme.  https://github.com/orderedlist/minimal.
142 | 
143 | 
144 | License
145 | -------
146 | 
147 | index.html, scale.fix.js, pygment_trac.css, styles.css: these are modified
148 | versions of https://github.com/orderedlist/minimal, which is licensed under a
149 | Creative Commons Attribution-ShareAlike 3.0 Unported License.
150 | http://creativecommons.org/licenses/by-sa/3.0/.
151 | 
152 | The remaining files in this repository are by Ewan Mellor, and are dedicated
153 | to the public domain.
154 | To the extent possible under law, Ewan Mellor has waived all copyright and
155 | related or neighboring rights to this work.
156 | http://creativecommons.org/publicdomain/zero/1.0/.
157 | 


--------------------------------------------------------------------------------