Merge branch 'main' into StevenClontz/add-jupyter-2

source/ch-jupyter.ptx

@@ -133,4 +133,105 @@ I've provided a
 that you can upload to your Codespace to experiment with.
     </p>
   </section>
+</chapter><?xml version='1.0' encoding='utf-8'?>
+<chapter xml:id="ch-jupyter">
+  <title>Jupyter Notebooks</title>
+  <introduction>
+    <p>
+In <xref ref="sec-run-code"/> you wrote and ran a few short
+scripts in various programming languages. But often, we want
+to not only be able to write and execute code, but do so
+piece-by-piece, and share the results with other people
+without requiring them to run the code themselves...
+    </p>
+  </introduction>
+  <section xml:id="sec-intro-to-jupyter">
+    <title>Intro to Jupyter</title>
+    <definition xml:id="def-jupyter">
+      <statement>
+        <p>
+A <term>Jupyter notebook</term> is a file that stores
+commentary, code, and output in an all-in-one format suitable for
+sharing with other people.
+        </p>
+      </statement>
+    </definition>
+    <p>
+Jupyter is a popular open-source tool used in
+data science, scientific computing, and computational journalism.
+GitHub provides a Codespace ready for running Jupyter notebooks
+out of the box:
+<url href="https://github.com/github/codespaces-jupyter/"/>.
+    </p>
+  </section>
+  <section xml:id="sec-github-codespaces-jupyter">
+    <title>GitHub's Jupyter Codespace</title>
+    <p>
+Let's begin by going to
+<url href="https://github.com/github/codespaces-jupyter/">
+  github/codespaces-jupyter</url>
+directly. Before we dive into editing a notebook ourselves,
+we can first browse the <c>notebooks</c> directory on
+the repository page. We see three files, each with the
+extension <c>*.ipynb</c>
+(short for <q><em>IPY</em>thon <em>N</em>ote<em>B</em>ook</q>,
+Jupyter's original name).
+    </p>
+    <p>
+Clicking on each file, you'll note that while there's code,
+most of the file is actually narrative and visualization.
+That's the appeal of Jupyter for many people: it's about
+communicating <em>stories</em>, not just data or software.
+    </p>
+    <p>
+Additionally, you'll see a <c>data</c> directory, which
+includes a <c>*.csv</c> <em>C</em>omma <em>S</em>eparated
+<em>V</em>alues spreadsheet. This file can be read into a
+notebook for analysis.
+    </p>
+    <p>
+Now, let's follow the instructions of the repository's
+README file (<xref ref="remark-readme"/>).
+    </p>
+  </section>
+  <!-- <section>
+    <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> -->
 </chapter>

source/main.ptx

@@ -21,6 +21,7 @@
     <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"/>