Merge pull request #9 from JimMadge/jupyter_os_instructions

Add windows installation instructions

Author: JimMadge

content/lessons/executable.md

@@ -11,6 +11,10 @@ kernelspec:
 
 MyST supports a number of ways to include executable content in your project.
 
+```{tip}
+Instructions are provided here for Jupyter Lab, however, you can use any IDE you are comfortable with. An explanation is provided on the [Software](#software) page.
+```
+
 ## Installing Jupyter
 
 Executable content in MyST is processed by a [Jupyter](xref:jupyter) server and appropriate [kernel](https://docs.jupyter.org/en/latest/glossary.html#term-kernel).
@@ -19,12 +23,40 @@ In this lesson, we will run a local Jupyter server to execute code cells.
 A pip requirements file, `requirements.txt` in the root of the repository specifies all of the dependencies you need.
 You can install all of these in a virtual environment using `pip` and then launch Jupyter.
 
+::::{tab-set}
+:::{tab-item} Linux and MacOS
 ```console
 python3 -m venv ./venv
 source ./venv/bin/activate
 pip install -r requirements.txt
 jupyter lab
 ```
+:::
+:::{tab-item} Windows
+```console
+python -m venv venv
+```
+
+For Command Prompt
+
+```console
+venv\Scripts\activate.bat
+```
+
+For PowerShell
+
+```console
+venv\Scripts\activate.ps1
+```
+
+Then
+
+```console
+pip install -r requirements.txt
+jupyter lab
+```
+:::
+::::
 
 This will automatically open the Jupyter Lab interface (at [localhost:8888](http://localhost:8888)) in your browser, which we will use later.
 

content/lessons/your_turn.md

@@ -1,21 +1,21 @@
 (lessons-start)=
 # Create your first Jupyter Book 2
 
-Now it's your turn to get going with creating content in a Jupyter Book.
+Now it's your turn to get going creating content in a Jupyter Book.
 
 There are some conditions to meet before you can get started:
 
-- Programming experience is not necessary, but it does make things a bit easier.
+- Programming and Git experience are not strictly necessary, but it does make things a bit easier.
 - A free [GitHub](https://github.com/) account.
 - A little bit of patience, it's a steep learning curve.
 
 Optional:
-- [Software](#software) to write your code in, such as [Visual Studio Code](https://code.visualstudio.com/) (VSC).
+- [Software](#software) to write your code in, such as Jupyter Lab or [Visual Studio Code](https://code.visualstudio.com/) (VSC).
 
 :::{tip}
 If you are feeling confident and would rather start building a document from scratch using the CLI on your computer, you can look at [the advanced start](#advanced-start) option 🌶.
 :::
 
-We provide instructions for building using the GitHub dev IDE, as well as building locally. For the latter we assume knowledge about VSC, and the use of git.
+We provide instructions for building using the GitHub development IDE, as well as building locally. For the latter we assume knowledge about VSC, and the use of git.
 
 Ready? Let's get started…

content/software.md

@@ -1,11 +1,34 @@
 (software)=
 # Software
 
-## VSC
-A popular code editor is [Visual Studio Code](https://code.visualstudio.com/). It allows you to program in different languages, where it recognizes the commands in that language and adjusts the FONT so that it becomes better readable. Moreover, it allows you to install various packages (such as Jupyter Notebook). It also integrates GIT and allows to code using Co-Pilot, an AI pair programmer. We advise to use VSC as it allows for multiple programming languages. 
+This page provides an overview of commonly used software, with limited instructions for using them. 
 
-### Terminal
-The terminal in Visual Studio Code (VSC) is a tool that lets you interact with your computer's command line directly within the editor. It's used to run commands, scripts, or programs without leaving the coding environment. For example, you can compile code, run a development server, install dependencies, or manage files. It's very helpful for developers because it allows you to code and execute commands in one place, streamlining your workflow.
+## Integrated Development Environment (IDE)
+
+An IDE is required to complete many of the exercises in this workshop. Many of them could be completed in a simple text editor, however, an IDE that includes features such as version control with Git, environment management and a CLI would be useful. As such, the instructions herein often refer to Jupyter Lab. However, you can choose your own IDE, noting that the main requirements are dictated by the use of Jupyeter Notebook (`*.ipynb`) files:
+
+- ability to edit notebooks natively (i.e., not editing the raw JSON),
+- access to a Jupyter server and Python kernel for executing notebooks.
+
+### Jupyter Lab
+
+To run Jupyter Notebooks we can use IDE’s as Jupyter Notebook or Jupyter Lab. Jupyter Notebook is a web-based interface that allows users to create and share documents with live code, visualizations, and narrative text in a linear format. Jupyter Lab, on the other hand, is a more advanced interface offering a flexible and modular environment with multiple panels, including notebooks, terminals, and text editors, providing a more versatile experience for interactive computing. I prefer to use Jupyter lab.
+
+### GitHub web-based editor
+
+The github.dev web editor makes it possible to edit files directly in the browser. This is an excellent option if you are unable to install software on your computer. To activate it, simply navigate to a GitHub repository and press `.`. It's really that easy!
+
+```{tip}
+Note that while this IDE can be used for many of the exercises in this workshop, and you can _edit_ Jupyter Notebook files, you will _not_ be able to use iexecute notebooks directly in the browser (however, notebooks will be executed during build in the GitHub Actions workflow).
+```
+
+You can find out more about this useful tool [here](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor).
+
+### VSC
+A popular code editor is [Visual Studio Code](https://code.visualstudio.com/) (VSC). It allows you to program in different languages, where it recognizes the commands in that language and adjusts the FONT so that it becomes better readable. Moreover, it allows you to install various packages (such as Jupyter Notebook). It also integrates GIT and allows to code using Co-Pilot, an AI pair programmer. We advise to use VSC as it allows for multiple programming languages. 
+
+#### Terminal
+The terminal in VSC is a tool that lets you interact with your computer's command line directly within the editor. It's used to run commands, scripts, or programs without leaving the coding environment. For example, you can compile code, run a development server, install dependencies, or manage files. It's very helpful for developers because it allows you to code and execute commands in one place, streamlining your workflow.
 
 ```{figure} figures/VSCterminal.*
 ---
@@ -15,10 +38,10 @@ width: 100%
 The VSC terminal to interact with the computer using the command line
 ```
 
-### Extensions
+#### Extensions
 Extensions in Visual Studio Code (VSC) are powerful add-ons that enhance the functionality of the editor by providing additional features, tools, and support for various programming languages, frameworks, and technologies. Extensions allow you to customize and tailor VSC to suit your specific development needs.
 
-#### How to Install Extensions:
+##### How to Install Extensions:
 - Access Extensions View:
     * Click on the Extensions icon in the Activity Bar on the side (or press Ctrl+Shift+X / Cmd+Shift+X).
 
@@ -31,7 +54,7 @@ Extensions in Visual Studio Code (VSC) are powerful add-ons that enhance the fun
 - Manage Installed Extensions:
     * You can view, enable, disable, or uninstall extensions from the same Extensions view.
 
-#### Popular Extensions in VSC:
+##### Popular Extensions in VSC:
 * Python: Provides linting, debugging, IntelliSense, and more for Python development.
 * Jupyter: Provides support for Jupyter notebooks within VSC.
 * Arduino: Provides support for programming in Arduino.
@@ -41,12 +64,10 @@ Extensions in Visual Studio Code (VSC) are powerful add-ons that enhance the fun
 * MyST-Markdown: The official Markdown syntax extension
 
 
-## MystMD
-
+## Requirements.txt
 
+A `requirements.txt` file is included for this workshop that contains the basic dependencies needed to complete it. Note in particular that 
 
-
-### Requirements.txt
 We included a [requirements.txt](../..requirements.txt) file with all dependencies that are likely to be used.
 These include:
 | Package | Description |
@@ -63,12 +84,5 @@ These include:
 
 If you are sure you want to install these dependencies, download the file, navigate through the correct folder and use `pip install -r requirements.txt`.
 
-
-
-## Jupyter lab
-
-We can make use of .ipynb files which are Jupyter Notebooks. To run these notebooks we can use IDE’s as Jupyter Notebook or Jupyter Lab. Jupyter Notebook is a web-based interface that allows users to create and share documents with live code, visualizations, and narrative text in a linear format. JupyterLab, on the other hand, is a more advanced interface offering a flexible and modular environment with multiple panels, including notebooks, terminals, and text editors, providing a more versatile experience for interactive computing. I prefer to use Jupyter lab.
-
-
 ## Typst
 For this template we use Typst to produce a high quality pdf. If you want to create pdf's locally, you'll have to install Typst. Follow the [Typst installation instructions](https://github.com/typst/typst?tab=readme-ov-file#installation) for several options to install Typst. We strongly recommend using the latest releases of Typst. If you get a confusing Typst error, a good first step is to upgrade your version of Typst.

myst.yml

@@ -65,6 +65,9 @@ project:
     CI/CD: Continuous Integration/Continuous Deployment
     GHA: GitHub Actions
     GH: GitHub
+    IDE: Integrated Development Environment
+    VSC: Visual Studio Code
+    CLI: commmand line interface
 
 
 site: