/
getting_started.Rmd
195 lines (147 loc) · 5.63 KB
/
getting_started.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
---
jupyter:
ipub:
pandoc:
convert_raw: true
hide_raw: false
at_notation: true
use_numref: true
jupytext:
metadata_filter:
notebook: ipub
text_representation:
extension: .Rmd
format_name: rmarkdown
format_version: '1.0'
jupytext_version: 0.8.6
kernelspec:
display_name: Python 3
language: python
name: python3
---
# Getting Started
## IPyPublish Basics
**This document is written in a Jupyter Notebook**
(or more precisely an RMarkdown version of the notebook),
which is executed and converted auto-magically to the page you are reading.
This is the power of IPyPublish!
```{python}
print("Hallo everybody!")
```
When analysing data with Python and Jupyter Notebooks, there are three 'modes'
we will be switching between:
- Writing and running analysis code (i.e. populating code cells)
- Documenting our analysis (i.e. populating markdown cells)
- Marking up and converting our notebooks to a distributable format
IPyPublish, in conjunction with some other great packages,
provides enhancements for working in each of these modes and the means to
seamlessly switch between them:
1. :ref:`code_cells`
2. :ref:`markdown_cells`
3. :ref:`notebook_conversion`
## Installation
Using [Conda](https://conda.io/docs/) is recommended for package
management, in order to create self contained environments with specific
versions of packages. The main external packages required are the
Jupyter notebook and [Pandoc](http://pandoc.org) (for markdown
conversion):
```console
$ conda create --name ipyreport -c conda-forge jupyter pandoc==2.6
$ source activate ipyreport
```
.. versionadded:: 0.9.3
ipypublish is now available on Conda (recommended):
```console
$ conda install -c conda-forge ipypublish
```
ipypublish can also be pip installed into this environment:
```console
$ pip install ipypublish
```
optionally, to include install dependencies for sphinx exporters:
```console
$ pip install ipypublish[sphinx]
```
For converting to PDF, the TeX document preparation ecosystem is
required, in particular
[latexmk](http://mg.readthedocs.io/latexmk.html)), which can be
installed from:
- Linux: [TeX Live](http://tug.org/texlive/)
- macOS (OS X): [MacTeX](http://tug.org/mactex/)
- Windows: [MikTex](http://www.miktex.org/)
For helpful extensions to the notebooks core capabilities, see the
[Jupyter Notebook Extensions
package](http://jupyter-contrib-nbextensions.readthedocs.io/en/latest/):
```console
$ conda install --name ipyreport jupyter_contrib_nbextensions
```
Additionally, a more extensive setup of useful packages (used to create
the examples) are provided by the [anaconda
distribution](https://docs.anaconda.com/anaconda/packages/pkg-docs/)
which can be installed in to a new environment
```console
$ conda create --name ipyreport anaconda
```
## Basic Conversion
The **nbpublish** script provides terminal access to the notebook
conversion application. To see all the options:
```console
$ nbpublish --help
```
To see all the conversion configurations:
```console
$ nbpublish -le
```
or to see a subset of configurations with a verbose description, use a regex:
```console
$ nbpublish -le *latex* -lv
```
To run a basic conversion to PDF and auto-load it in a web browser
```console
$ nbpublish -pdf -lb -f latex_ipypublish_nocode path/to/notebook.ipynb
```
For a more detailed explanation see the
`notebook_conversion`{.interpreted-text role="ref"} section.
.. important::
The default conversion (``latex_ipypublish_main``) will **NOT**
output any cells that are not tagged with metadata.
To output all notebook content by default, use ``_ipypublish_all``.
.. tip::
For existing notebooks: the **nb_ipypublish_all** and
**nb_ipypublish_nocode** converters (see below) can be helpful for
outputting a notebook, with identical content to that input, but with
default metatags defining how content is to be output.
The **nbpresent** script additionally handles serving
[reveal.js](http://lab.hakim.se/reveal-js/#/) slides to a webbrowser.
```console
$ nbpresent -h
$ nbpresent -f slides_ipypublish_nocode path/to/notebook.ipynb
```
.. note::
For offline use, simply download the latest version of reveal.js
[here](https://github.com/hakimel/reveal.js/releases), rename the entire
folder to reveal.js and place it in the same folder as the converted
.slides.html file. The slides can also be saved to PDF by appending
`pdf-export` to the url (see
[here](https://github.com/hakimel/reveal.js#pdf-export) for details).
## Troubleshooting
For installation issues, GitHub Actions is used to automatically
test updates against multiple Python versions, for Linux, Windows and OSX,
Therefore, to troubleshoot any installation/run issues, it is best to
first look at the [test workflow](https://github.com/chrisjsewell/ipypublish/blob/master/.github/workflows/tests.yml)
and [test runs](https://github.com/chrisjsewell/ipypublish/actions)
for working configurations.
The
[requirements-lock.txt](https://github.com/chrisjsewell/ipypublish/blob/master/requirements-lock.txt)
file can also be used to provide exact versions of working package
dependencies.
For conversion issues, for both `nbpublish` and `nbpresent`, detailed
log messages of the run are output to both the console and file (default
path: converted/notebook\_name.nbpub.log). Try running with options:
```console
$ nbpublish --log-level debug --print-traceback notebook.ipynb
```
To debug PDF conversions, use the `--pdf-debug` flag. If there is still
an error, please raise an issue on the [GitHub
repository](https://github.com/chrisjsewell/ipypublish/issues),
including the run environment and the log file.