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>

source/ch-collaboration.ptx

@@ -22,6 +22,17 @@ edit your repository's text files with you via their web
 browser. When you commit your
 changes, they will be listed as co-authors of the commit.
     </p>
+    <remark>
+      <p>
+As of writing, my experience with LiveShare has been hit-or-miss,
+so I'll suggest another mechanism for live collaboration.
+Sometimes when I'm working on a Git repository
+with a collague on Zoom, I'll share my screen and give my collaborator
+control of my mouse and keyboard, or vice versa. Obviously
+you should only do this with a collaborator you trust, but it's
+a simple solution to quickly work together on the same repo!
+      </p>
+    </remark>
   </section>
   <section xml:id="sec-collaborators-prs">
     <title>Collaborators and Pull Requests</title>

source/ch-first-repo.ptx

@@ -73,18 +73,26 @@ see <xref ref="ch-collaboration"/>.)
         <p>
 An easy way to edit an individual file is just to click
 the pencil icon such as the one that appears on your README.
-This file is written in <term>Markdown</term>, a markup language
-that takes plain text <c>like *this*</c> and renders it
-<q>like <em>this</em></q>.
+This file is written in <q>Markdown</q>.
         </p>
+        <definition xml:id="def-markdown">
+                <statement>
+                        <p>
+<term>Markdown</term> is a markup language
+that takes plain text <c>like *this*</c> and renders it
+<q>like <em>this</em></q>. Sites like
+<url href="https://www.MarkdownTutorial.com"/> and
+<url href="https://www.MarkdownGuide.org"/> offer more
+complete tutorials.
+                        </p>
+                </statement>
+        </definition>
         <p>
 Try to edit your file to say something like <q>I'm learning how to
 use GitHub!</q>, perhaps adding a link back to this document
 using <c>[this markup](https://g4m.clontz.org)</c>. You
-can click the Preview tab to see what your README will look like,
-and visit sites like <url href="https://www.MarkdownTutorial.com"/> or
-<url href="https://www.MarkdownGuide.org"/> to learn
-more. GitHub also provides a panel of several formatting options
+can click the Preview tab to see what your README will look like.
+GitHub also provides a panel of several formatting options
 you can click on.
         </p>
         <p>

source/ch-jupyter.ptx

@@ -56,47 +56,81 @@ notebook for analysis.
     </p>
     <p>
 Now, let's follow the instructions of the repository's
-README file (<xref ref="remark-readme"/>).
+README file (<xref ref="remark-readme"/>). As of writing,
+it recommends to just use the <c>Code</c> button to open
+a Codespace, without needing to fork (<xref ref="sec-forks"/>)
+the repository. This allows you to <q>try out</q> the Codespace
+without saving your work long-term, but you can still create a fork
+with your changes later if you decide to.
     </p>
   </section>
-  <!-- <section>
+  <section xml:id="sec-jupyter-kernel">
+    <title>Kernels</title>
     <p>
-      To get started, create a Codespace
-      (<xref ref="note-create-codespace"/>)
-      on either an existing or new repository
-      (<xref ref="sec-creating-the-repo"/>).
-      You can then create a Jupyter notebook file named
-      <c>notebook.ipynb</c>.
-          </p>
-          <note xml:id="note-provision-notebook">
-            <p>
-      In a Codespace, any file with the extension 
-      will be treated as a
-      Jupyter notebook. When opening this file, you'll see a notebook
-      interface, and be prompted to
-      <q>install the recommended 'Python' extension</q> if it's
-      not already enabled - do this.
-            </p>
-            <p>
-      Then in your notebook file, click the <q>Select Kernel</q>
-      button, then <q>Install/Enable suggested extensions</q> for
-      Python+Jupyter. You should then have the option to select
-      a <q>Python environment</q> such as <c>Python 3.*.*</c>.
-            </p>
-            <p>
-      If successful, you should be able to enter
-      <c>import sys; print(sys.version)</c> into the displayed
-      text box,
-      and see the result of executing it with
-      <kbd>Shift</kbd>+<kbd>Enter</kbd>.
-            </p>
-          </note>
-          <p>
-      There are plenty of existing tutorials on the internet to help you
-      get acquainted with Python and Jupyter now that you have them
-      available to you in your Codespace. But to get you started, I've provided
-      one <dataurl source="first-notebook.ipynb">sample notebook</dataurl>
-      that you can upload to your Codespace to break the ice.
-          </p>
-  </section> -->
+At the core of any Jupyter notebook is its <q>kernel</q>.
+    </p>
+    <definition xml:id="def-kernel">
+      <statement>
+        <p>
+The <term>kernel</term> of a Jupyter notebook is a process that wires up
+a notebook to a particular programming language.
+        </p>
+      </statement>
+    </definition>
+    <p>
+Kernels for several different programming languages exist. We will use
+a Python kernel in this book, not least of which because it's one of the
+most commonly used kernels, and the kernel that's already set up for use
+with the GitHub Jupyter Codespace repo.
+    </p>
+    <p>
+In your Codespace, use the <q>Select kernel</q> button, to choose
+a <q>Python environment</q>. You should be able to select the default
+global environment without needing to create a new one. Your notebook
+is ready once you see <c>Python 3.x.y</c> (for some values of <m>x,y</m>)
+in the upper-right corner of the notebook.
+    </p>
+  </section>
+  <section xml:id="sec-cells">
+    <title>Cells</title>
+    <p>
+A notebook is composed of many consecutive parts, known as <q>cells</q>.
+    </p>
+    <definition xml:id="def-cells">
+      <statement>
+        <p>
+A <term>cell</term> of a notebook encapsulates either
+commentary/documentation (as a <term>Markdown cell</term>) or
+code (as a <term>Code cell</term>). Cells can be rearranged,
+inserted, cut, pasted, and so on.
+        </p>
+      </statement>
+    </definition>
+    <p>
+Each Markdown cell uses, well, Markdown (<xref ref="def-markdown"/>)
+to describe content that should be displayed to the reader, similar
+to a README file in your repository.
+    </p>
+    <p>
+But it's the Code cells that set a notebook apart. Each Code cell
+in a notebook is run consecutively, with the result of the final
+line of code being displayed for the reader. Importantly, these
+outputs are saved to the notebook itself, meaning that by sharing
+the notebook with a colleague, they can see the output of your
+code without running it themselves! This is not only convenient,
+but it's essential when communicating the result of code that
+uses software your reader does not have installed themselves.
+Likewise, it allows for showing the results of code via a web
+browser, such as at
+<url href="https://github.com/github/codespaces-jupyter/blob/main/notebooks/image-classifier.ipynb">this link</url>.
+    </p>
+  </section>
+  <section xml:id="sec-sample-notebook">
+    <title>A sample notebook</title>
+    <p>
+I've provided a
+<dataurl source="first-notebook.ipynb">sample notebook</dataurl>
+that you can upload to your Codespace to experiment with.
+    </p>
+  </section>
 </chapter>

source/main.ptx

@@ -21,8 +21,8 @@
     <xi:include href="ch-first-repo.ptx"/>
     <xi:include href="ch-website.ptx"/>
     <xi:include href="ch-coding.ptx"/>
-    <xi:include href="ch-jupyter.ptx"/>
     <xi:include href="ch-collaboration.ptx"/>
+    <xi:include href="ch-jupyter.ptx"/>
     <xi:include href="ch-projects.ptx"/>
     <xi:include href="ch-manim.ptx"/>