Commit 7b6e8071 authored by lorenzwalthert's avatar lorenzwalthert
Browse files

more verbose readme

parent 3db48c3b
# .Rprofile generated from teamtools::init_team_repo(). Do not edit by hand # .Rprofile generated from teamtools::init_team_repo(). Do not edit by hand
if ("teamtools" %in% utils::installed.packages()[, "Package"]) { # if ("teamtools" %in% utils::installed.packages()[, "Package"]) {
cli::cat_bullet("Sourcing .Rprofile from team root.", # cli::cat_bullet("Sourcing .Rprofile from team root.",
bullet = "tick", col = "green" # bullet = "tick", col = "green"
) # )
team_root_rprof <- file.path(teamtools::find_team_root(), ".rprofile") # team_root_rprof <- file.path(teamtools::find_team_root(), ".rprofile")
if (!file.exists(team_root_rprof)) { # if (!file.exists(team_root_rprof)) {
writeLines("", team_root_rprof) # writeLines("", team_root_rprof)
} else { # } else {
source(team_root_rprof) # source(team_root_rprof)
} # }
} else { # } else {
message("Please install teamtools with remotes::install_github('lorenzwalthert/teamtools')") # message("Please install teamtools with remotes::install_github('lorenzwalthert/teamtools')")
} # }
...@@ -15,8 +15,8 @@ knitr::opts_chunk$set( ...@@ -15,8 +15,8 @@ knitr::opts_chunk$set(
# A few words from the authors {-} # A few words from the authors {-}
This repository is a bookdown template, derived from the LaTeX template This repository is a bookdown template, derived from the LaTeX template from the
from the semiar for statistics, ETH Zurich. semiar for statistics, ETH Zurich.
**How bookdown works** **How bookdown works**
...@@ -26,8 +26,7 @@ In a nutshell, bookdown works as follows: ...@@ -26,8 +26,7 @@ In a nutshell, bookdown works as follows:
* use pandoc to convert markdown to latex, pdf, word, html books (with featuers * use pandoc to convert markdown to latex, pdf, word, html books (with featuers
like font size, background selection, full text search etc), epub. like font size, background selection, full text search etc), epub.
The basic workflow is as follows:
The basic workflow is as follows:
* Change a source file: In our template, the source of the body of the thesis * Change a source file: In our template, the source of the body of the thesis
is under `./rmd/`. For example, change `02-features.Rmd`. To make sure only is under `./rmd/`. For example, change `02-features.Rmd`. To make sure only
...@@ -38,35 +37,40 @@ The basic workflow is as follows: ...@@ -38,35 +37,40 @@ The basic workflow is as follows:
* Re-compile the book using Cmd + Shift + B (for build) on a Mac and Ctrl + * Re-compile the book using Cmd + Shift + B (for build) on a Mac and Ctrl +
Shift + B on Windows / Linux. Shift + B on Windows / Linux.
* You can customize the build in the RStudio Build Tab, where you can specify * 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 which output (html, pdf, etc.) you want to generate. This is remembered for the
the next build you are doing.s next build you are doing.s
**Getting started** **Getting started**
Fork the upstream repository and clone the fork. Then, you will have one remote 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 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 upstream remote so you can later rebase on it in case you need. We recommend
using ssh over https. using ssh over https.
**Why using bookdown** **Why using bookdown**
The advantages of using bookdown instead of plain LaTeX are, in the eyes of the The advantages of using bookdown instead of plain LaTeX are, in the eyes of the
creator of this template: creator of this template:
* Generalization. Not just latex or PDF output, but any output supported by * Generalization. Not just latex or PDF output, but any output supported by
Pandoc. Pandoc, e.g. Word and html.
* The best of two worlds. Use intuitive markdown syntax where possible, use * The best of two worlds. Use intuitive markdown syntax where possible, use the
the full power of LaTeX syntax where needed. This includes a real-time latex full power of LaTeX syntax where needed. This includes a real-time latex
equation previewer in RStudio, bibtex reference, LaTeX cross-, text- and equation previewer in RStudio, bibtex reference, LaTeX cross-, text- and figure
figure reference. reference.
* It's native R. Integrate R code and R output in your writing has never been * It's native R. Integrate R code and R output such as plots, tables, figures
easier than with bookdown. You can also use other languages supported by directly in your writing has never been easier than with bookdown. You can turn
knitr such as python, stan etc.^[Below, we even used the bash command `tree` a data frame into a latex table using the power of R packages such as
to show the directory structure of this repo. Since unicode is not suppored `kableExtra`.
with pdflatex, we used R code to tell knitr to use the tree command * You can also use other languages supported by knitr such as
with the option `charset unicode` for pdf output and without it for html python, stan etc.^[Below, we even used the bash command `tree` to show the
output.] 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.]
* Because it's native R, you can place R variables in the floating text. Check
out the Rmd source of this document to see that we used R to compute the square
root of three (`r sqrt(3)`), print todays date with `Sys.Date()` right into the
text: `r Sys.Date()`
**How this template works** **How this template works**
...@@ -85,69 +89,68 @@ tree -d -L 2 --charset unicode ...@@ -85,69 +89,68 @@ tree -d -L 2 --charset unicode
* figure: Contains figures you created from your (R) code in the rmd source. * figure: Contains figures you created from your (R) code in the rmd source.
* images: Put images you want to include in your thesis in this folder. * 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. * pdf: Put PDFs you want to include in your thesis in this folder.
* rmd: The source folder of thesis. When you build a book, the following * 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 happens: By default, all rmd files in this folder get merged into one big rmd
rmd file, according to their name. We suggest to use one file per chapter. file, according to their name. We suggest to use one file per chapter. Then, the
Then, the file containing all the rmd sources will get processed by knitr and file containing all the rmd sources will get processed by knitr and later by
later by Pandoc. Pandoc.
* scratch: A random directory which is not tracked by git by default. The idea * 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 is that you can put things that are not ready to commit or that have a temporary
temporary character here. character here.
* style: Latex .sty files. Taken from the sfs LaTeX template. * style: Latex .sty files. Taken from the sfs LaTeX template.
* tex: All tex data, most importantly, the sfs LaTeX template itself. Note that * 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. the abstract, preface, epilogue, summary, notation are still in tex, i.e. you
you need to change these files if you want the PDF output to change. This need to change these files if you want the PDF output to change. This will
will **not** affect the html output. You can create chapters that show **not** affect the html output. You can create chapters that show up in a
up in a particular output and not in the other forms as shown in particular output and not in the other forms as shown in
`rmd/99-references.Rmd`. `rmd/99-references.Rmd`.
Furthermore, we want to highlight a few files in the root directory of the Furthermore, we want to highlight a few files in the root directory of the
project: project:
* `DESCRIPTION`: You can use it to declare dependent packages of your thesis in * `DESCRIPTION`: You can use it to declare dependent packages of your thesis in
the `Imports:` field. If someone want's to rebuild you thesis from scratch, the `Imports:` field. If someone want's to rebuild you thesis from scratch, the
the can use `remotes::install_deps()` to satisfy all R package dependencies. can use `remotes::install_deps()` to satisfy all R package dependencies.
* `index.Rmd`: Contains a YAML header where a few important variables are defined. * `index.Rmd`: Contains a YAML header where a few important variables are
You can also put markdown below the header. defined. You can also put markdown below the header.
* `README.(R)md`: This document. * `README.(R)md`: This document.
* `thesis-template-bookdown.Rproj`: An RStudio project. We recommend using * `thesis-template-bookdown.Rproj`: An RStudio project. We recommend using
RStudio for authoring your master thesis with bookdown. RStudio for authoring your master thesis with bookdown.
**A few recommendations** **A few recommendations**
* We strongly suggest to use a different folder for the data / code of your * 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 thesis and reserve this directory for the thesis document only. You can reaname
reaname this directory `analysis-communication` (since this will be the this directory `analysis-communication` (since this will be the means used for
means used for communicating the results and process of your thesis) and communicating the results and process of your thesis) and use `analysis-raw` for
use `analysis-raw` for the code and `data` for all data. Ideally, you the code and `data` for all data. Ideally, you place them in the same directory
place them in the same directory so you can still work with relative paths, so you can still work with relative paths, e.g. `../data`.
e.g. `../data`.
* We suggest to use git version control for the thesis and the raw analsyis. * 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. * If your thesis is open source, you can use netlify.com to deploy it, i.e. for
for every commit you push to a remote repo like GitHub, you can use netlify's every commit you push to a remote repo like GitHub, you can use netlify's CLI to
CLI to build your book on a CI machine like travis. See file `travis.yml` for build your book on a CI machine like travis. See file `travis.yml` for the
the bookdown book bookdown book [Advanced
[Advanced R](https://github.com/hadley/adv-r/tree/88dcb07e2b2ae634af6cdeafff2f3ea976077064) R](https://github.com/hadley/adv-r/tree/88dcb07e2b2ae634af6cdeafff2f3ea976077064)
for an example. That makes tracking the `_book` folder in git redundant. for an example. That makes tracking the `_book` folder in git redundant.
**Further material** **Further material**
This is obviously a very short introduction to the template and it is in no way 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 comprehensive. To learn more about bookdown, we encourage the reader to have a
a look at the [bookdown guide](https://bookdown.org/yihui/bookdown/) as well look at the [bookdown guide](https://bookdown.org/yihui/bookdown/) as well as
as searching through stack overflow / Google for particular questions. In searching through stack overflow / Google for particular questions. In addition,
addition, inspect the different files in this repo, in particular the ones inspect the different files in this repo, in particular the ones in the rmd
in the rmd directory to develop a deeper understanding of the template. directory to develop a deeper understanding of the template.
As of early 2018, this template is still in alpha testing phase, so you may As of early 2018, this template is still in alpha testing phase, so you may
experience unexpected behavior. Please file an issue on the git repository experience unexpected behavior. Please file an issue on the git repository where
where you have obtained the source of this template in case you have obtained the source of this template in case you are stuck for some
you are stuck for some time with a problem or if you found a solution to a time with a problem or if you found a solution to a problem you believe others
problem you believe others are likely to encounter in the future. Pull requests are likely to encounter in the future. Pull requests on typos are also welcome.
on typos are also welcome. We want to We want to make sure that students working this template have a great experience
make sure that students working this template have a great experience writing writing their master thesis.
their master thesis.
Best, Best,
Nicola Gnecco and Lorenz Walthert Nicola Gnecco and Lorenz Walthert
<!-- README.md is generated from README.Rmd. Please edit that file --> <!-- README.md is generated from README.Rmd. Please edit that file -->
# 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**
In a nutshell, bookdown works as follows:
- 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.
The basic workflow is as follows:
- Change a source file: In our template, the source of the body of the
thesis 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>).
- Re-compile the book using Cmd + Shift + B (for build) on a Mac and
Ctrl + Shift + B on Windows / Linux.
- 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
**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.
**Why using bookdown**
The advantages of using bookdown instead of plain LaTeX are, in the eyes
of the creator of this template:
- Generalization. Not just latex or PDF output, but any output
supported by Pandoc, e.g. Word and html.
- 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 such as plots, tables,
figures directly in your writing has never been easier than with
bookdown. You can turn a data frame into a latex table using the
power of R packages such as `kableExtra`.
- You can also use other languages supported by knitr such as python,
stan etc.\[1\]
- Because it’s native R, you can place R variables in the floating
text. Check out the Rmd source of this document to see that we used
R to compute the square root of three (1.7320508), print todays date
with `Sys.Date()` right into the text: 2018-09-23
**How this template works**
There are different directories in this template:
``` bash
tree -d -L 2 --charset unicode
#> .
#> |-- _book
#> | |-- figures
#> | |-- libs
#> | |-- man
#> | `-- thesis_SfS_files
#> |-- _bookdown_files
#> | `-- thesis_SfS_files
#> |-- bib
#> |-- figure
#> |-- figures
#> |-- images
#> | `-- auto
#> |-- pdf
#> |-- rmd
#> |-- scratch
#> |-- style
#> `-- tex
#>
#> 17 directories
```
- \_book: Contains the compiled book, e.g. a PDF or html version.
- \_bib: Contains BibTeX reference data bases.
- figure: Contains figures you created from your (R) code in the rmd
source.
- 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.
- 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 later by Pandoc.
- 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.
- 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`.
Furthermore, we want to highlight a few files in the root directory of
the project:
- `DESCRIPTION`: You can use it to declare dependent packages of your
thesis in the `Imports:` field. If someone want’s to rebuild you
thesis from scratch, the can use `remotes::install_deps()` to
satisfy all R package dependencies.
- `index.Rmd`: Contains a YAML header where a few important variables
are defined. You can also put markdown below the header.
- `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**
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 as searching
through stack overflow / Google for particular questions. In 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 experience unexpected behavior. Please file an issue on the git
repository 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 problem you believe others are likely to encounter in the future. Pull
requests on typos are also welcome. We want to make sure that students
working this template have a great experience writing their master
thesis.
Best,
Nicola Gnecco and Lorenz Walthert
1. 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.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment