diff --git a/assets/sample-notebook.ipynb b/assets/first-notebook.ipynb similarity index 100% rename from assets/sample-notebook.ipynb rename to assets/first-notebook.ipynb diff --git a/assets/screenshots/codespace-python-extension.png b/assets/screenshots/codespace-python-extension.png new file mode 100644 index 0000000..2049124 Binary files /dev/null and b/assets/screenshots/codespace-python-extension.png differ diff --git a/assets/screenshots/codespace-python-script.png b/assets/screenshots/codespace-python-script.png new file mode 100644 index 0000000..284dabf Binary files /dev/null and b/assets/screenshots/codespace-python-script.png differ diff --git a/requirements.txt b/requirements.txt index f1e2ba8..17aca4d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,2 @@ # -pretext == 2.4.2.dev20240629061947 +pretext == 2.6.0 diff --git a/source/ch-coding.ptx b/source/ch-coding.ptx index 08a988c..b4b55c4 100644 --- a/source/ch-coding.ptx +++ b/source/ch-coding.ptx @@ -110,55 +110,135 @@ would like your Codespace to periodically run

-
- Python and Jupyter Notebooks +
+ Writing and Running Code

-Python 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 -Jupyter notebook. +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.

-To get started, create a Codespace -() -on either an existing or new repository -(). -You can then create a Jupyter notebook file named -notebook.ipynb. +Our first example will be Python, a popular general-purpose programming +language (and the same language we will use in +for Jupyter notebooks). In your Codespace, right-click on the file Explorer +to create a New File.... Name this file something.py so your +Codespace recognizes the file as a Python script (due to the .py file +extension). +This should trigger the prompt shown in +to install a Python extension - go ahead and do it.

- -

-In a Codespace, any file with the extension *.ipynb -(short for IPYthon NoteBook, -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 -install the recommended 'Python' extension if it's -not already enabled - do this. -

-

-Then in your notebook file, click the Select Kernel -button, then Install/Enable suggested extensions for -Python+Jupyter. You should then have the option to select -a Python environment such as Python 3.*.*. -

-

-If successful, you should be able to enter -import sys; print(sys.version) into the displayed -text box, -and see the result of executing it with -Shift+Enter. -

- +
+ + +A screenshot of the prompt that displays in a Codespace +to install the Python extension. + + + Prompt to install the Python extension. +
+

+Add the line print("Hello world!") to your file. +A play icon (▶) 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 . +

+
+ + +A screenshot of a Python script being executed within a Codespace. + + + Running a Python script in a Codespace. +
+

+Unless your Codespace has been customized via a +.devcontainer.json 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. +

+ + +

+A terminal is a command-line prompt used to +run programs that don't have a graphical user interface. +Type the command and hit Enter to run it. +

+ + + + +

+To open a terminal on demand in a Codespace, use the shortcut +Ctrl/Cmd+Shift+`. +

+ +

-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 sample notebook -that you can upload to your Codespace to break the ice. +What do you think the programs in +, +, and + +will output? Copy-paste them into a file in your Codespace, +then run to find out!

+ + + +# 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 + + + Sample Python code + + + + +# 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 + + + Sample Ruby code + + + + +// 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 +}) + + + + Sample Javascript code +
Previewing GitHub Pages @@ -171,7 +251,7 @@ on GitHub.com and create a new Codespace

To spin up your live preview, open a terminal by using the -Ctrl/Cmd+Shift+` keys. To make +shortcut noted in . To make sure the necessary software has been installed, type bundle and hit Enter. Then, you can enter jekyll serve to start the preview server. diff --git a/source/ch-first-repo.ptx b/source/ch-first-repo.ptx index fe7f704..f03cb95 100644 --- a/source/ch-first-repo.ptx +++ b/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 GitHub.com.

+ +

+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. +

+

Finally, you might be interested in visiting the Insights tab for your repository, and specifically the Network page. diff --git a/source/ch-jupyter.ptx b/source/ch-jupyter.ptx new file mode 100644 index 0000000..c6228b7 --- /dev/null +++ b/source/ch-jupyter.ptx @@ -0,0 +1,102 @@ + + + Jupyter Notebooks + +

+In 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... +

+ +
+ Intro to Jupyter + + +

+A Jupyter notebook is a file that stores +commentary, code, and output in an all-in-one format suitable for +sharing with other people. +

+ + +

+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: +. +

+
+
+ GitHub's Jupyter Codespace +

+Let's begin by going to + + github/codespaces-jupyter +directly. Before we dive into editing a notebook ourselves, +we can first browse the notebooks directory on +the repository page. We see three files, each with the +extension *.ipynb +(short for IPYthon NoteBook, +Jupyter's original name). +

+

+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 stories, not just data or software. +

+

+Additionally, you'll see a data directory, which +includes a *.csv Comma Separated +Values spreadsheet. This file can be read into a +notebook for analysis. +

+

+Now, let's follow the instructions of the repository's +README file (). +

+
+ + \ No newline at end of file diff --git a/source/main.ptx b/source/main.ptx index 96a55a9..1df7433 100644 --- a/source/main.ptx +++ b/source/main.ptx @@ -21,6 +21,7 @@ +