You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+73-183
Original file line number
Diff line number
Diff line change
@@ -4,195 +4,69 @@
4
4
5
5
`gophernotes` is a Go kernel for [Jupyter](http://jupyter.org/) notebooks and [nteract](https://nteract.io/). It lets you use Go interactively in a browser-based notebook or desktop app. Use `gophernotes` to create and share documents that contain live Go code, equations, visualizations and explanatory text. These notebooks, with the live Go code, can then be shared with others via email, Dropbox, GitHub and the [Jupyter Notebook Viewer](http://nbviewer.jupyter.org/). Go forth and do data science, or anything else interesting, with Go notebooks!
6
6
7
-
This project utilizes a Go interpreter called [gomacro](https://github.com/cosmos72/gomacro) under the hood to evaluate Go code interactively.
7
+
**Acknowledgements** - This project utilizes a Go interpreter called [gomacro](https://github.com/cosmos72/gomacro) under the hood to evaluate Go code interactively. The gophernotes logo was designed by the brilliant [Marcus Olsson](https://github.com/marcusolsson) and was inspired by Renee French's original Go Gopher design.
8
8
9
9
## Examples
10
10
11
-
Jupyter Notebook:
11
+
### Jupyter Notebook:
12
+
12
13
13
14
14
-
nteract:
15
+
### nteract:
16
+
15
17
16
18
17
19
### Example Notebooks (dowload and run them locally, follow the links to view in Github, or use the [Jupyter Notebook Viewer](http://nbviewer.jupyter.org/)):
18
-
-[Simple Printing and Channels](https://github.com/gopherds/gophernotes/blob/master/examples/Simple-Example.ipynb)
19
-
-[Pattern Recognition with Golearn](https://github.com/gopherds/gophernotes/blob/master/examples/Pattern-Recognition.ipynb)
- Pull down and run the [latest image](https://hub.docker.com/r/dwhitena/gophernotes/):
30
-
31
-
```
32
-
docker pull dwhitena/gophernotes:latest
33
-
docker run --name gophernotes --net host -d dwhitena/gophernotes:latest
34
-
```
35
-
36
-
*Possible issues* - For OSX Docker Machine / Dlite users, you may need to set the IP to `0.0.0.0` instead of the default `localhost` with:
37
-
38
-
```
39
-
docker run -p 8888:8888 -d dwhitena/gophernotes jupyter notebook --no-browser --ip=0.0.0.0
40
-
```
41
-
42
-
*Note* - this is a pretty large image, because it contains a full distribution of [Anaconda](http://docs.continuum.io/anaconda/index) plus the add ons of gophernotes. However, with this image, you can create Go notebooks, Python notebooks, text files, run ipython in the shell, etc.
43
-
44
-
### Local, Linux
45
-
46
-
Make sure you have the following dependencies:
47
-
48
-
-[Go](https://golang.org/) 1.5+
49
-
- Jupyter (see [here](http://jupyter.readthedocs.org/en/latest/install.html) for more details on installing jupyter)
50
-
-[ZeroMQ](http://zeromq.org/) (2.2.X or 4.x)
26
+
### Prerequisites
51
27
52
-
Then:
53
-
54
-
1. Create a workspace and setup your `GOPATH`, see https://golang.org/doc/code.html#GOPATH
55
-
56
-
2. Install `goimports` if you haven't already:
57
-
58
-
```
59
-
go get golang.org/x/tools/cmd/goimports
60
-
```
28
+
-[Go 1.9+](https://golang.org/doc/install) - including GOPATH/bin added to your PATH (i.e., you can run Go binaries that you `go install`).
29
+
-[Jupyter Notebook](http://jupyter.readthedocs.io/en/latest/install.html) or [nteract](https://nteract.io/desktop)
30
+
-[ZeroMQ 4.X.X](http://zeromq.org/intro:get-the-software) - for convenience, pre-built Windows binaries (v4.2.1) are included in the zmq-win directory.
61
31
62
-
3. Get the kernel:
63
-
- with ZeroMQ 2.2.x:
32
+
### Linux
64
33
65
-
```
66
-
go get github.com/gopherds/gophernotes
67
-
```
68
-
69
-
- with ZeroMQ 4.x:
70
-
71
-
```
72
-
go get -tags zmq_4_x github.com/gopherds/gophernotes
Note, depending on which version of jupyter you are using and if you are using Anaconda, you may need to copy to `~/.ipython` rather than `~/.local/share`:
Note, if you have the `JUPYTER_PATH` environmental variable set or if you are using an older version of Jupyter, you may need to copy this kernel config to another directory. You can check which directories will be searched by executing:
94
-
95
-
```
96
-
jupyter --data-dir
97
-
```
98
-
99
-
### Local, OSX
100
-
101
-
Make sure you have the following dependencies:
102
-
103
-
- [Go](https://golang.org/) 1.5+
104
-
- Jupyter (see [here](http://jupyter.readthedocs.org/en/latest/install.html) for more details on installing jupyter)
Note, if you have the `JUPYTER_PATH` environmental variable set or if you are using an older version of Jupyter, you may need to copy this kernel config to another directory. You can check which directories will be searched by executing:
47
+
**Note** - if you have the `JUPYTER_PATH` environmental variable set or if you are using an older version of Jupyter, you may need to copy this kernel config to another directory. You can check which directories will be searched by executing:
152
48
153
-
```
154
-
jupyter --data-dir
155
-
```
156
-
157
-
4. Update `~/Library/Jupyter/kernels/gophernotes/kernel.json` with the FULL PATH to your gophernotes binary (in $GOPATH/bin). For example:
49
+
```sh
50
+
$ jupyter --data-dir
51
+
```
158
52
159
-
```
160
-
{
161
-
"argv": [
162
-
"/Users/<yourusername>/go/bin/gophernotes",
163
-
"{connection_file}"
164
-
],
165
-
"display_name": "Go",
166
-
"language": "go",
167
-
"name": "go"
168
-
}
169
-
```
53
+
### OS X/macOS
170
54
171
-
### Local, Windows
55
+
### Windows
172
56
173
-
Make sure you have the following dependencies:
57
+
Make sure you have the MinGW toolchain:
174
58
175
-
- [Go](https://golang.org/) 1.5+ with cgo enabled
176
-
- MinGW toolchain, such as:
177
59
- [MinGW-w64](https://sourceforge.net/projects/mingw-w64/), for 32 and 64 bit Windows
178
60
- [MinGW Distro](https://nuwen.net/mingw.html), for 64 bit Windows only
179
-
- Jupyter (see [here](http://jupyter.readthedocs.org/en/latest/install.html) for more details on installing jupyter)
180
-
- [ZeroMQ](http://zeromq.org/) (2.2.X or 4.x); for convenience, pre-built binaries (v4.2.1) are included in the zmq-win directory
181
61
182
-
Then:
183
-
184
-
1. Install goimports, if not already installed:
185
-
186
-
```
187
-
go get golang.org/x/tools/cmd/goimports
188
-
```
62
+
Then:
189
63
190
-
2. Build and install gophernotes (using the pre-built binaries and `zmq-win\build.bat`):
64
+
1. build and install gophernotes (using the pre-built binaries and `zmq-win\build.bat`):
191
65
192
66
```
193
67
REM Download w/o building.
194
-
go get -d github.com/gopherds/gophernotes
195
-
cd %GOPATH%\src\github.com\gopherds\gophernotes\zmq-win
68
+
go get -d github.com/gopherdata/gophernotes
69
+
cd %GOPATH%\src\github.com\gopherdata\gophernotes\zmq-win
Note, if you have the `JUPYTER_PATH` environmental variable set or if you are using an older version of Jupyter, you may need to copy this kernel config to another directory. You can check which directories will be searched by executing:
@@ -232,27 +106,60 @@ Then:
232
106
}
233
107
```
234
108
109
+
### Docker
110
+
111
+
You can try out or run Jupyter + gophernotes without installing anything using Docker. To run a Go notebook that only needs things from the standard library, run:
112
+
113
+
```
114
+
$ docker run -it -p 8888:8888 gopherdata/gophernotes
115
+
```
116
+
117
+
Or to run a Go notebook with access to common Go data science packages (gonum, gota, golearn, etc.), run:
118
+
119
+
```
120
+
$ docker run -it -p 8888:8888 gopherdata/gophernotes-ds
121
+
```
122
+
123
+
In either case, running this command should output a link that you can follow to access Jupyter in a browser.
235
124
236
125
## Getting Started
237
126
238
-
- If you completed one of the local installs above (i.e., not the Docker install), start the jupyter notebook:
127
+
### Jupyter
128
+
129
+
- If you completed one of the local installs above (i.e., not the Docker install), start the jupyter notebook server:
239
130
240
131
```
241
132
jupyter notebook
242
133
```
243
134
244
-
- If you have a docker install, point a browser at `http://localhost:8888/`.
135
+
- Select `Go` from the `New` drop down menu.
136
+
137
+
- Have fun!
138
+
139
+
### nteract
140
+
141
+
- Launch nteract.
245
142
246
-
- Select `Golang` from the `New` drop down menu.
143
+
- From the nteract menu select Language -> Go.
247
144
248
-
- Have Fun!
145
+
- Have fun!
249
146
147
+
## Limitations
148
+
149
+
gophernotes uses [gomacro](https://github.com/cosmos72/gomacro) under the hood to evaluate Go code interactively. You can evaluate most any Go code with gomacro, but there are some limitation, which are discussed in further detail [here](https://github.com/cosmos72/gomacro#current-status). Most noteably, gophernotes does NOT support:
150
+
151
+
- unexported struct fields
152
+
- interfaces - They can be declared, but nothing more: there is no way to implement them or call their methods
153
+
- extracting methods from types - For example time.Duration.String should return a func(time.Duration) string but currently gives an error. Instead extracting methods from objects is supported: time.Duration(1s).String correctly returns a func() string
154
+
- goto
155
+
- named return values
156
+
- named imports
250
157
251
158
## Troubleshooting
252
159
253
160
### gophernotes not found
254
-
- Depending on your environment, you may need to manually change the path to the `gophernotes` executable in `kernel/kernel.json` before copying it to `~/.local/share/jupyter/kernels/gophernotes`. You can put the **full path** to the `gophernotes` executable here, and you shouldn't have any further issues.
255
161
162
+
Depending on your environment, you may need to manually change the path to the `gophernotes` executable in `kernel/kernel.json` before copying it to `~/.local/share/jupyter/kernels/gophernotes`. You can put the **full path** to the `gophernotes` executable here, and you shouldn't have any further issues.
Restart jupyter, and you should now be up and running.
280
-
281
-
282
-
## Custom Commands
283
-
Some of the custom commands from the [gore](https://github.com/motemen/gore) REPL have carried over to `gophernotes`. Note, in particular, the syntax for importing packages:
284
-
285
-
```
286
-
:print Show current source (currently prints to the terminal where the notebook server is running)
287
-
:write[<filename>] Write out current source to file
288
-
:help List commands
289
-
:containerize Build a Docker image that executes the compiled Go code (must have Docker installed)
290
-
```
291
-
292
-
## Licenses
293
-
294
-
`gophernotes` was created by [Daniel Whitenack](http://www.datadan.io/), and is licensed under an [MIT-style License](LICENSE.md).
295
-
296
-
The Golang Gopher image adapted for the gophernotes logo was created by [Takuya Ueda](http://u.hinoichi.net) and is licensed under the Creative Commons 3.0 Attributions license.
0 commit comments