Skip to content

Commit 868e092

Browse files
StevenClontzDanielHodgins
StevenClontz
and
DanielHodgins
authored
new jupyter chapter (#33)
* update pretext * add jupyter chapter stub * move old jupyter stuff, add vanilla programming stuff * Update source/ch-coding.ptx Co-authored-by: Daniel Hodgins <121420574+DanielHodgins@users.noreply.github.com> * add terminal info * fix merge mistake * whitespace * add more on jupyter notebook chapter * various edits * usable chapter * fix merge * fix dupe jupyter chapter --------- Co-authored-by: Daniel Hodgins <121420574+DanielHodgins@users.noreply.github.com>
1 parent 1ed1f50 commit 868e092

6 files changed

Lines changed: 294 additions & 48 deletions

File tree

‎assets/git-branches-source.xml‎

Lines changed: 193 additions & 0 deletions
Large diffs are not rendered by default.

‎assets/git-branches.png‎

34.2 KB
Loading

‎source/ch-collaboration.ptx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,17 @@ edit your repository's text files with you via their web
2222
browser. When you commit your
2323
changes, they will be listed as co-authors of the commit.
2424
</p>
25+
<remark>
26+
<p>
27+
As of writing, my experience with LiveShare has been hit-or-miss,
28+
so I'll suggest another mechanism for live collaboration.
29+
Sometimes when I'm working on a Git repository
30+
with a collague on Zoom, I'll share my screen and give my collaborator
31+
control of my mouse and keyboard, or vice versa. Obviously
32+
you should only do this with a collaborator you trust, but it's
33+
a simple solution to quickly work together on the same repo!
34+
</p>
35+
</remark>
2536
</section>
2637
<section xml:id="sec-collaborators-prs">
2738
<title>Collaborators and Pull Requests</title>

‎source/ch-first-repo.ptx‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -73,18 +73,26 @@ see <xref ref="ch-collaboration"/>.)
7373
<p>
7474
An easy way to edit an individual file is just to click
7575
the pencil icon such as the one that appears on your README.
76-
This file is written in <term>Markdown</term>, a markup language
77-
that takes plain text <c>like *this*</c> and renders it
78-
<q>like <em>this</em></q>.
76+
This file is written in <q>Markdown</q>.
7977
</p>
78+
<definition xml:id="def-markdown">
79+
<statement>
80+
<p>
81+
<term>Markdown</term> is a markup language
82+
that takes plain text <c>like *this*</c> and renders it
83+
<q>like <em>this</em></q>. Sites like
84+
<url href="https://www.MarkdownTutorial.com"/> and
85+
<url href="https://www.MarkdownGuide.org"/> offer more
86+
complete tutorials.
87+
</p>
88+
</statement>
89+
</definition>
8090
<p>
8191
Try to edit your file to say something like <q>I'm learning how to
8292
use GitHub!</q>, perhaps adding a link back to this document
8393
using <c>[this markup](https://g4m.clontz.org)</c>. You
84-
can click the Preview tab to see what your README will look like,
85-
and visit sites like <url href="https://www.MarkdownTutorial.com"/> or
86-
<url href="https://www.MarkdownGuide.org"/> to learn
87-
more. GitHub also provides a panel of several formatting options
94+
can click the Preview tab to see what your README will look like.
95+
GitHub also provides a panel of several formatting options
8896
you can click on.
8997
</p>
9098
<p>

‎source/ch-jupyter.ptx‎

Lines changed: 74 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -56,47 +56,81 @@ notebook for analysis.
5656
</p>
5757
<p>
5858
Now, let's follow the instructions of the repository's
59-
README file (<xref ref="remark-readme"/>).
59+
README file (<xref ref="remark-readme"/>). As of writing,
60+
it recommends to just use the <c>Code</c> button to open
61+
a Codespace, without needing to fork (<xref ref="sec-forks"/>)
62+
the repository. This allows you to <q>try out</q> the Codespace
63+
without saving your work long-term, but you can still create a fork
64+
with your changes later if you decide to.
6065
</p>
6166
</section>
62-
<!-- <section>
67+
<section xml:id="sec-jupyter-kernel">
68+
<title>Kernels</title>
6369
<p>
64-
To get started, create a Codespace
65-
(<xref ref="note-create-codespace"/>)
66-
on either an existing or new repository
67-
(<xref ref="sec-creating-the-repo"/>).
68-
You can then create a Jupyter notebook file named
69-
<c>notebook.ipynb</c>.
70-
</p>
71-
<note xml:id="note-provision-notebook">
72-
<p>
73-
In a Codespace, any file with the extension
74-
will be treated as a
75-
Jupyter notebook. When opening this file, you'll see a notebook
76-
interface, and be prompted to
77-
<q>install the recommended 'Python' extension</q> if it's
78-
not already enabled - do this.
79-
</p>
80-
<p>
81-
Then in your notebook file, click the <q>Select Kernel</q>
82-
button, then <q>Install/Enable suggested extensions</q> for
83-
Python+Jupyter. You should then have the option to select
84-
a <q>Python environment</q> such as <c>Python 3.*.*</c>.
85-
</p>
86-
<p>
87-
If successful, you should be able to enter
88-
<c>import sys; print(sys.version)</c> into the displayed
89-
text box,
90-
and see the result of executing it with
91-
<kbd>Shift</kbd>+<kbd>Enter</kbd>.
92-
</p>
93-
</note>
94-
<p>
95-
There are plenty of existing tutorials on the internet to help you
96-
get acquainted with Python and Jupyter now that you have them
97-
available to you in your Codespace. But to get you started, I've provided
98-
one <dataurl source="first-notebook.ipynb">sample notebook</dataurl>
99-
that you can upload to your Codespace to break the ice.
100-
</p>
101-
</section> -->
70+
At the core of any Jupyter notebook is its <q>kernel</q>.
71+
</p>
72+
<definition xml:id="def-kernel">
73+
<statement>
74+
<p>
75+
The <term>kernel</term> of a Jupyter notebook is a process that wires up
76+
a notebook to a particular programming language.
77+
</p>
78+
</statement>
79+
</definition>
80+
<p>
81+
Kernels for several different programming languages exist. We will use
82+
a Python kernel in this book, not least of which because it's one of the
83+
most commonly used kernels, and the kernel that's already set up for use
84+
with the GitHub Jupyter Codespace repo.
85+
</p>
86+
<p>
87+
In your Codespace, use the <q>Select kernel</q> button, to choose
88+
a <q>Python environment</q>. You should be able to select the default
89+
global environment without needing to create a new one. Your notebook
90+
is ready once you see <c>Python 3.x.y</c> (for some values of <m>x,y</m>)
91+
in the upper-right corner of the notebook.
92+
</p>
93+
</section>
94+
<section xml:id="sec-cells">
95+
<title>Cells</title>
96+
<p>
97+
A notebook is composed of many consecutive parts, known as <q>cells</q>.
98+
</p>
99+
<definition xml:id="def-cells">
100+
<statement>
101+
<p>
102+
A <term>cell</term> of a notebook encapsulates either
103+
commentary/documentation (as a <term>Markdown cell</term>) or
104+
code (as a <term>Code cell</term>). Cells can be rearranged,
105+
inserted, cut, pasted, and so on.
106+
</p>
107+
</statement>
108+
</definition>
109+
<p>
110+
Each Markdown cell uses, well, Markdown (<xref ref="def-markdown"/>)
111+
to describe content that should be displayed to the reader, similar
112+
to a README file in your repository.
113+
</p>
114+
<p>
115+
But it's the Code cells that set a notebook apart. Each Code cell
116+
in a notebook is run consecutively, with the result of the final
117+
line of code being displayed for the reader. Importantly, these
118+
outputs are saved to the notebook itself, meaning that by sharing
119+
the notebook with a colleague, they can see the output of your
120+
code without running it themselves! This is not only convenient,
121+
but it's essential when communicating the result of code that
122+
uses software your reader does not have installed themselves.
123+
Likewise, it allows for showing the results of code via a web
124+
browser, such as at
125+
<url href="https://github.com/github/codespaces-jupyter/blob/main/notebooks/image-classifier.ipynb">this link</url>.
126+
</p>
127+
</section>
128+
<section xml:id="sec-sample-notebook">
129+
<title>A sample notebook</title>
130+
<p>
131+
I've provided a
132+
<dataurl source="first-notebook.ipynb">sample notebook</dataurl>
133+
that you can upload to your Codespace to experiment with.
134+
</p>
135+
</section>
102136
</chapter>

‎source/main.ptx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@
2121
<xi:include href="ch-first-repo.ptx"/>
2222
<xi:include href="ch-website.ptx"/>
2323
<xi:include href="ch-coding.ptx"/>
24-
<xi:include href="ch-jupyter.ptx"/>
2524
<xi:include href="ch-collaboration.ptx"/>
25+
<xi:include href="ch-jupyter.ptx"/>
2626
<xi:include href="ch-projects.ptx"/>
2727
<xi:include href="ch-manim.ptx"/>
2828

0 commit comments

Comments
 (0)