Add Jupyter chapter (#30)

* 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

---------

Co-authored-by: Daniel Hodgins <121420574+DanielHodgins@users.noreply.github.com>

requirements.txt

@@ -1,2 +1,2 @@
 # <!-- Managed automatically by PreTeXt authoring tools -->
-pretext == 2.4.2.dev20240629061947
+pretext == 2.6.0

source/ch-coding.ptx

@@ -110,55 +110,135 @@ would like your Codespace to periodically run
       </p>
     </note>
   </section>
-  <section xml:id="sec-jupyter-notebooks">
-    <title>Python and Jupyter Notebooks</title>
+  <section xml:id="sec-run-code">
+    <title>Writing and Running Code</title>
     <p>
-<url href="https://python.org">Python</url> is an
-popular open-source all-purpose programming language, and
-a convenient way to write, execute, and share the
-results of Python code is a
-<url href="https://jupyter.org/">Jupyter notebook</url>.
+Now that we've provisioned our Codespace virtual cloud computer,
+we can use it to write and execute code using our web browser for
+essentially any programming lanugage.
     </p>
     <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>.
+Our first example will be Python, a popular general-purpose programming
+language (and the same language we will use in <xref ref="ch-jupyter"/>
+for Jupyter notebooks). In your Codespace, right-click on the file Explorer
+to create a <q>New File...</q>. Name this file <c>something.py</c> so your
+Codespace recognizes the file as a Python script (due to the <c>.py</c> file
+extension).
+This should trigger the prompt shown in <xref ref="fig-python-extension-screenshot"/>
+to install a Python extension - go ahead and do it.
     </p>
-    <note xml:id="note-provision-notebook">
-      <p>
-In a Codespace, any file 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)
-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>
+    <figure xml:id="fig-python-extension-screenshot">
+      <image width="100%" source="screenshots/codespace-python-extension.png">
+        <shortdescription>
+A screenshot of the prompt that displays in a Codespace
+to install the Python extension.
+        </shortdescription>
+      </image>
+      <caption>Prompt to install the Python extension.</caption>
+    </figure>
+    <p>
+Add the line <c>print("Hello world!")</c> to your file.
+A <q>play</q> icon (<kbd>▶</kbd>) should be displayed
+in the upper-right corner of the text editor (thanks to the
+Python extension you installed). Clicking
+this button should execute the code to print a greeting
+as in <xref ref="fig-python-script-screenshot"/>.
+    </p>
+    <figure xml:id="fig-python-script-screenshot">
+      <image width="100%" source="screenshots/codespace-python-script.png">
+        <shortdescription>
+A screenshot of a Python script being executed within a Codespace.
+        </shortdescription>
+      </image>
+      <caption>Running a Python script in a Codespace.</caption>
+    </figure>
+    <p>
+Unless your Codespace has been customized via a
+<c>.devcontainer.json</c> file (which we won't get
+into here), you'll be using the default Codespace
+image provided by GitHub. This environment is ready
+to execute code from various standard programming
+lanugages, though for some of them you may
+need to run the script using the Terminal.
+    </p>
+    <definition xml:id="def-terminal">
+      <statement>
+        <p>
+A <term>terminal</term> is a command-line prompt used to
+run programs that don't have a graphical user interface.
+Type the command and hit <kbd>Enter</kbd> to run it.
+        </p>
+      </statement>
+    </definition>
+    <remark xml:id="remark-terminal-shortcut">
+      <statement>
+        <p>
+To open a terminal on demand in a Codespace, use the shortcut
+<kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>`</kbd>.
+        </p>
+      </statement>
+    </remark>
     <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="sample-notebook.ipynb">sample notebook</dataurl>
-that you can upload to your Codespace to break the ice.
+What do you think the programs in
+<xref ref="listing-python-fib"/>,
+<xref ref="listing-ruby-fib"/>, and
+<xref ref="listing-javascript-fib"/>
+will output? Copy-paste them into a file in your Codespace,
+then run to find out!
     </p>
+    <listing xml:id="listing-python-fib">
+      <program language="python">
+        <input>
+# name this Python file something.py
+# execute using the ▶ button or by running this in a terminal:
+#   python something.rb
+a,b = 1,1
+print(a)
+print(b)
+for _ in range(10):
+  print(a+b)
+  a,b = b,a+b
+        </input>
+      </program>
+      <caption>Sample Python code</caption>
+    </listing>
+    <listing xml:id="listing-ruby-fib">
+      <program language="ruby">
+        <input>
+# name this Ruby file something.rb
+# execute by running this in a terminal:
+#   ruby something.rb
+a,b = 1,1
+puts a
+puts b
+10.times do
+  puts a+b
+  a,b = b,a+b
+end
+        </input>
+      </program>
+      <caption>Sample Ruby code</caption>
+    </listing>
+    <listing xml:id="listing-javascript-fib">
+      <program language="javascript">
+        <input>
+// name this Javascript file something.js
+// execute by running this in a terminal:
+//   node something.js
+let a = 1, b = 1
+console.log(a)
+console.log(b)
+Array.from({ length: 10 }, _ => {
+  console.log(a+b)
+  let _a = a
+  a = b
+  b = _a + b
+})
+
+        </input>
+      </program>
+      <caption>Sample Javascript code</caption>
+    </listing>
   </section>
   <section xml:id="sec-github-pages-codespace">
     <title>Previewing GitHub Pages</title>
@@ -171,7 +251,7 @@ on <c>GitHub.com</c> and create a new Codespace
     </p>
     <p>
 To spin up your live preview, open a terminal by using the
-<kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>`</kbd> keys. To make
+shortcut noted in <xref ref="remark-terminal-shortcut"/>. To make
 sure the necessary software has been installed, type <c>bundle</c>
 and hit <kbd>Enter</kbd>. Then, you can enter <c>jekyll serve</c>
 to start the preview server.

source/ch-first-repo.ptx

@@ -97,6 +97,15 @@ summarizing the work you've done since your last commit
 Doing this will update the README visible on your repository
 homepage on <c>GitHub.com</c>.
         </p>
+        <remark xml:id="remark-readme">
+                <p>
+README files are important! If you ever want to share your
+repository source with someone else, it's the first thing
+they will read. Likewise, if you want to use someone else's
+repository, they will hopefully include first steps in their
+own README file.
+                </p>
+        </remark>
         <p>
 Finally, you might be interested in visiting the <q>Insights</q>
 tab for your repository, and specifically the <q>Network</q> page.

source/ch-jupyter.ptx

@@ -0,0 +1,102 @@
+<?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-projects.ptx"/>
     <xi:include href="ch-manim.ptx"/>