To receive notifications about scheduled maintenance, please subscribe to the mailing-list gitlab-operations@sympa.ethz.ch. You can subscribe to the mailing-list at https://sympa.ethz.ch

README.Rmd 6.59 KB
Newer Older
lorenzwalthert's avatar
lorenzwalthert committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "figures/README-",
  out.width = "100%"
)
```

# A few words from the authors {-}

This repository is a bookdown template, derived from the LaTeX template 
from the semiar for statistics, ETH Zurich. 

**How bookdown works**
lorenzwalthert's avatar
lorenzwalthert committed
22

lorenzwalthert's avatar
lorenzwalthert committed
23
In a nutshell, bookdown works as follows:
lorenzwalthert's avatar
lorenzwalthert committed
24
25
26
27
28

* use knitr to convert Rmd to markdown.
* use pandoc to convert markdown to latex, pdf, word, html books (with featuers
  like font size, background selection, full text search etc), epub.

lorenzwalthert's avatar
lorenzwalthert committed
29
30
31
32

The basic workflow is as follows: 

* Change a source file: In our template, the source of the body of the thesis
Lorenz Walthert's avatar
Lorenz Walthert committed
33
34
35
36
37
  is under `./rmd/`. For example, change `02-features.Rmd`. To make sure only
  files from this directory are used, get the devel versio of bookdown  and 
  add a corresponding confirugartion 
  (for details, see https://github.com/rstudio/bookdown/issues/242).
  
lorenzwalthert's avatar
lorenzwalthert committed
38
39
* Re-compile the book using Cmd + Shift + B (for build) on a Mac and Ctrl + 
  Shift + B on Windows / Linux.
lorenzwalthert's avatar
lorenzwalthert committed
40
41
42
* You can customize the build in the RStudio Build Tab, where you can specify
  which output (html, pdf, etc.) you want to generate. This is remembered for 
  the next build you are doing.s
lorenzwalthert's avatar
lorenzwalthert committed
43

lorenzwalthert's avatar
lorenzwalthert committed
44
45
46
47
48
49
50
51
**Getting started**

Fork the upstream repository and clone the fork. Then, you will have one remote
repository: origin, which refers to the fork. Add the upstream repo as an 
upstream remote so you can later rebase on it in case you need. We recommend
using ssh over https.


lorenzwalthert's avatar
lorenzwalthert committed
52
53
54
**Why using bookdown**

The advantages of using bookdown instead of plain LaTeX are, in the eyes of the 
lorenzwalthert's avatar
lorenzwalthert committed
55
creator of this template:
lorenzwalthert's avatar
lorenzwalthert committed
56
57
58
59
60
61
62
63
64

* Generalization. Not just latex or PDF output, but any output supported by 
  Pandoc.
* The best of two worlds. Use intuitive markdown syntax where possible, use 
  the full power of LaTeX syntax where needed. This includes a real-time latex
  equation previewer in RStudio, bibtex reference, LaTeX cross-, text- and 
  figure reference.
* It's native R. Integrate R code and R output in your writing has never been
  easier than with bookdown. You can also use other languages supported by 
lorenzwalthert's avatar
lorenzwalthert committed
65
66
67
68
69
  knitr such as python, stan etc.^[Below, we even used the bash command `tree`
  to show the directory structure of this repo. Since unicode is not suppored
  with pdflatex, we used R code to tell knitr to use the tree command 
  with the option `charset unicode` for pdf output and without it for html 
  output.] 
lorenzwalthert's avatar
lorenzwalthert committed
70
71
72

**How this template works**

lorenzwalthert's avatar
lorenzwalthert committed
73
There are different directories in this template:
lorenzwalthert's avatar
lorenzwalthert committed
74

lorenzwalthert's avatar
lorenzwalthert committed
75
```{bash, include = knitr::is_html_output()}
lorenzwalthert's avatar
lorenzwalthert committed
76
77
78
tree -d -L 2
```

lorenzwalthert's avatar
lorenzwalthert committed
79
80
81
82
83
84
```{bash, include = !knitr::is_html_output()}
tree -d -L 2 --charset unicode
```

* _book: Contains the compiled book, e.g. a PDF or html version.
* _bib: Contains BibTeX reference data bases.
lorenzwalthert's avatar
lorenzwalthert committed
85
* figure: Contains figures you created from your (R) code in the rmd source.
lorenzwalthert's avatar
lorenzwalthert committed
86
87
* images: Put images you want to include in your thesis in this folder.
* pdf: Put PDFs you want to include in your thesis in this folder.
lorenzwalthert's avatar
lorenzwalthert committed
88
89
90
91
* rmd: The source folder of thesis. When you build a book, the following 
  happens: By default, all rmd files in this folder get merged into one big 
  rmd file, according to their name. We suggest to use one file per chapter.
  Then, the file containing all the rmd sources will get processed by knitr and 
lorenzwalthert's avatar
lorenzwalthert committed
92
  later by Pandoc.
lorenzwalthert's avatar
lorenzwalthert committed
93
94
95
* scratch: A random directory which is not tracked by git by default. The idea
  is that you can put things that are not ready to commit or that have a 
  temporary character here.
lorenzwalthert's avatar
lorenzwalthert committed
96
97
98
99
100
101
102
103
* style: Latex .sty files. Taken from the sfs LaTeX template.
* tex: All tex data, most importantly, the sfs LaTeX template itself. Note that 
  the abstract, preface, epilogue, summary, notation are still in tex, i.e. 
  you need to change these files if you want the PDF output to change. This 
  will **not** affect the html output. You can create chapters that show 
  up in a particular output and not in the other forms as shown in 
  `rmd/99-references.Rmd`.
  
lorenzwalthert's avatar
lorenzwalthert committed
104
105
106
Furthermore, we want to highlight a few files in the root directory of the
project:

lorenzwalthert's avatar
lorenzwalthert committed
107
* `DESCRIPTION`: You can use it to declare dependent packages of your thesis in 
lorenzwalthert's avatar
lorenzwalthert committed
108
  the `Imports:` field. If someone want's to rebuild you thesis from scratch,
lorenzwalthert's avatar
lorenzwalthert committed
109
  the can use `remotes::install_deps()` to satisfy all R package dependencies.
lorenzwalthert's avatar
lorenzwalthert committed
110
* `index.Rmd`: Contains a YAML header where a few important variables are defined.
lorenzwalthert's avatar
lorenzwalthert committed
111
  You can also put markdown below the header.
lorenzwalthert's avatar
lorenzwalthert committed
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
* `README.(R)md`: This document.
* `thesis-template-bookdown.Rproj`: An RStudio project. We recommend using 
  RStudio for authoring your master thesis with bookdown.

**A few recommendations**

* We strongly suggest to use a different folder for the data / code of your 
  thesis and reserve this directory for the thesis document only. You can 
  reaname this directory `analysis-communication` (since this will be the
  means used for communicating the results and process of your thesis) and
  use `analysis-raw` for the code and `data` for all data. Ideally, you 
  place them in the same directory so you can still work with relative paths,
  e.g. `../data`.
* We suggest to use git version control for the thesis and the raw analsyis.
* If your thesis is open source, you can use netlify.com to deploy it, i.e. 
  for every commit you push to a remote repo like GitHub, you can use netlify's
  CLI to build your book on a CI machine like travis. See file `travis.yml` for
  the bookdown book 
  [Advanced R](https://github.com/hadley/adv-r/tree/88dcb07e2b2ae634af6cdeafff2f3ea976077064)
  for an example. That makes tracking the `_book` folder in git redundant.

**Further material**

lorenzwalthert's avatar
lorenzwalthert committed
135
136
137
This is obviously a very short introduction to the template and it is in no way
comprehensive. To learn more about bookdown, we encourage the reader to have 
a look at the [bookdown guide](https://bookdown.org/yihui/bookdown/) as well 
lorenzwalthert's avatar
lorenzwalthert committed
138
as searching through stack overflow / Google for particular questions. In 
lorenzwalthert's avatar
lorenzwalthert committed
139
140
141
142
addition, inspect the different files in this repo, in particular the ones 
in the rmd directory to develop a deeper understanding of the template. 

As of early 2018, this template is still in alpha testing phase, so you may 
lorenzwalthert's avatar
lorenzwalthert committed
143
experience unexpected behavior. Please file an issue on the git repository
lorenzwalthert's avatar
lorenzwalthert committed
144
145
where you have obtained the source of this template in case 
you are stuck for some time with a problem or if you found a solution to a 
lorenzwalthert's avatar
lorenzwalthert committed
146
147
problem you believe others are likely to encounter in the future. Pull requests
on typos are also welcome. We want to 
lorenzwalthert's avatar
lorenzwalthert committed
148
149
150
151
152
153
make sure that students working this template have a great experience writing 
their master thesis.

Best,

Nicola Gnecco and Lorenz Walthert