Show an HTML-extracted copy of Jupyter-based SRS notebooks on the website.

.github/workflows/Build.yaml

@@ -127,6 +127,12 @@ jobs:
         run: make mdbook_build
         if: ${{ steps.changes.outputs.md == 'true' || fromJSON(env.is_deployment) }}
 
+      - name: "Extract HTML copies of Jupyter Notebooks"
+        run: |
+          sudo apt-get install -y --fix-missing jupyter
+          make jupyter_html
+        if: ${{ steps.changes.outputs.md == 'true' || fromJSON(env.is_deployment) }}
+
       - name: "Build website generator"
         run: make website
 

code/Makefile

@@ -78,6 +78,7 @@ INSTALL_E_SUFFIX = _install
 DEBUG_E_SUFFIX = _debug
 MDBOOK_BUILD_E_SUFFIX = _mdbook_build
 MDBOOK_SERVER_E_SUFFIX = _mdbook_server
+JUPYTER_HTML_E_SUFFIX = _juphtml
 
 # add example names with the appropriate suffixes to create per-example targets
 GEN_EXAMPLES = $(addsuffix $(GEN_E_SUFFIX), $(EXAMPLES))
@@ -92,6 +93,7 @@ INSTALL_EXAMPLES = $(addsuffix $(INSTALL_E_SUFFIX), $(EXAMPLES))
 DEBUG_EXAMPLES = $(addsuffix $(DEBUG_E_SUFFIX), $(EXAMPLES))
 MDBOOK_BUILD_EXAMPLES = $(addsuffix $(MDBOOK_BUILD_E_SUFFIX), $(EXAMPLES))
 MDBOOK_SERVER_EXAMPLES = $(addsuffix $(MDBOOK_SERVER_E_SUFFIX), $(EXAMPLES))
+JUPYTER_HTML_EXAMPLES = $(addsuffix $(JUPYTER_HTML_E_SUFFIX), $(EXAMPLES))
 
 # Website names with appropriate suffixes.
 TEST_WEBSITE = $(addsuffix $(TEST_E_SUFFIX), $(WEBSITE_FOLDER_NAME))
@@ -287,15 +289,17 @@ packagedeps: graphmod check_dot
 # and then build the generated mdBook projects.
 mdbook_build: $(MDBOOK_BUILD_EXAMPLES) ##@Examples Build all generated mdBook projects.
 
+jupyter_html: $(JUPYTER_HTML_EXAMPLES) ##@Examples Extract HTML copies from all Jupyter SRS Notebooks.
+
 #--------------------------------------------------------------#
 #--- Targets that are used for individual packages/examples ---#
 #--------------------------------------------------------------#
 # Use filter to make a target for every package (second argument of filter)
 # with an appended suffix (first argument of filter).
 
 # Variables needed to create individual example targets using filter.
-%$(GEN_E_SUFFIX) %$(TEST_E_SUFFIX) %$(STABILIZE_E_SUFFIX) %$(BC_E_SUFFIX) %$(TRACE_GRAPH_SUFFIX) %$(INSTALL_E_SUFFIX) %$(MDBOOK_BUILD_E_SUFFIX) %$(MDBOOK_SERVER_E_SUFFIX): EXAMPLE=$(shell echo $* | tr a-z A-Z)
-%$(GEN_E_SUFFIX) %$(TEST_E_SUFFIX) %$(STABILIZE_E_SUFFIX) %$(BC_E_SUFFIX) %$(TRACE_GRAPH_SUFFIX) %$(INSTALL_E_SUFFIX) %$(MDBOOK_BUILD_E_SUFFIX) %$(MDBOOK_SERVER_E_SUFFIX): EDIR=$($(EXAMPLE)_DIR)
+%$(GEN_E_SUFFIX) %$(TEST_E_SUFFIX) %$(STABILIZE_E_SUFFIX) %$(BC_E_SUFFIX) %$(TRACE_GRAPH_SUFFIX) %$(INSTALL_E_SUFFIX) %$(MDBOOK_BUILD_E_SUFFIX) %$(MDBOOK_SERVER_E_SUFFIX) %$(JUPYTER_HTML_E_SUFFIX): EXAMPLE=$(shell echo $* | tr a-z A-Z)
+%$(GEN_E_SUFFIX) %$(TEST_E_SUFFIX) %$(STABILIZE_E_SUFFIX) %$(BC_E_SUFFIX) %$(TRACE_GRAPH_SUFFIX) %$(INSTALL_E_SUFFIX) %$(MDBOOK_BUILD_E_SUFFIX) %$(MDBOOK_SERVER_E_SUFFIX) %$(JUPYTER_HTML_E_SUFFIX): EDIR=$($(EXAMPLE)_DIR)
 %$(GEN_E_SUFFIX) %$(TRACE_GRAPH_SUFFIX) %$(INSTALL_E_SUFFIX): EEXE=$($(EXAMPLE)_EXE)
 
 # Build individual Drasil packages. Each package will have the target packageName_build.
@@ -407,6 +411,10 @@ $(filter %$(MDBOOK_SERVER_E_SUFFIX), $(MDBOOK_SERVER_EXAMPLES)): %$(MDBOOK_SERVE
 	- "$(SHELL)" "$(SCRIPT_FOLDER)copy_example_assets.sh" "$(BUILD_FOLDER)$(EDIR)/SRS/mdBook"
 	mdbook serve --open "$(BUILD_FOLDER)$(EDIR)/SRS/mdBook"
 
+# Targets will have the form exampleName_juphtml.
+$(filter %$(JUPYTER_HTML_E_SUFFIX), $(JUPYTER_HTML_EXAMPLES)): %$(JUPYTER_HTML_E_SUFFIX): %$(GEN_E_SUFFIX)
+	jupyter nbconvert --to html "$(BUILD_FOLDER)$(EDIR)/SRS/Jupyter/*.ipynb"
+
 #----------------------------------------------------------------------------------#
 #--- Generate analysis of module, class, datatype, and class instance structure ---#
 #----------------------------------------------------------------------------------#
@@ -587,6 +595,7 @@ help:  ##@Help Show this help.
 	@echo "  X$(DCP_E_SUFFIX)  Get all generated code file paths in the example."
 	@echo "  X$(MDBOOK_BUILD_E_SUFFIX)      Build the mdBook SRS of an individual example."
 	@echo "  X$(MDBOOK_SERVER_E_SUFFIX)     Launch local server for the mdBook SRS of an individual example."
+	@echo "  X$(JUPYTER_HTML_E_SUFFIX)           Extract an HTML copy out of a Juypter Notebook."
 	@echo ""
 	@echo "Set a 'DEBUG_ENV' environment variable to 'true' if you want to check out the list of chunks in a Drasil run."
 	@echo ""
@@ -604,4 +613,4 @@ help_packages: ##@Help Lists all packages.
 		echo "  $$package"; \
 	done
 
-.PHONY: help setup_debug_vars clean clean_artifacts cleanArtifacts gool code deps hlint hot_hlint analysis tex doc debug test graphs graphmod check_stack nographs graphs website deploy_code_path deploy deploy_lite all install examples tracegraphs doxygen shellcheck mdbook_build $(GOOLTEST) $(ALL_EXPANDED_TARGETS)
+.PHONY: help setup_debug_vars clean clean_artifacts cleanArtifacts gool code deps hlint hot_hlint analysis tex doc debug test graphs graphmod check_stack nographs graphs website deploy_code_path deploy deploy_lite all install examples tracegraphs doxygen shellcheck mdbook_build jupyter_html $(GOOLTEST) $(ALL_EXPANDED_TARGETS)

code/drasil-printers/lib/Language/Drasil/Printers.hs

@@ -1,7 +1,7 @@
 module Language.Drasil.Printers (
   -- * Formats
   DocType(SRS, Website, Lesson), 
-  Format(TeX, HTML, Jupyter, MDBook)
+  Format(..)
   -- * DOT
   -- ** Types
   , GraphInfo(..), NodeFamily(..)
@@ -36,11 +36,10 @@ module Language.Drasil.Printers (
   , HasPrintingOptions (..)
   , Notation(..)
   , defaultConfiguration
-  )
-  where
+) where
 
 import Language.Drasil.Format (DocType(SRS, Website, Lesson), 
-  Format(TeX, HTML,  Jupyter, MDBook))
+  Format(..))
 import Language.Drasil.HTML.CSS (makeCSS)
 import Language.Drasil.HTML.Print (genHTML)
 import Language.Drasil.JSON.Print (genJupyter)

code/drasil-website/lib/Drasil/Website/Example.hs

@@ -95,7 +95,8 @@ individualExList ex@E{systemE = SI{_sys = sys}, codePath = srsP} =
   [Flat $ namedRef (buildDrasilExSrcRef ex) (S "Drasil Source Code"),
   Flat $ S "SRS:" +:+ namedRef (getSRSRef srsP HTML $ programName sys) (S "[HTML]") 
   +:+ namedRef (getSRSRef srsP TeX $ programName sys) (S "[PDF]")
-  +:+ namedRef (getSRSRef srsP MDBook $ programName sys) (S "[mdBook]"),
+  +:+ namedRef (getSRSRef srsP MDBook $ programName sys) (S "[mdBook]")
+  +:+ namedRef (getSRSRef srsP Jupyter $ programName sys) (S "[Jupyter (HTML)]"),
   Nested (S generatedCodeTitle) $ Bullet $ map (, Nothing) (versionList getCodeRef ex),
   Nested (S generatedCodeDocsTitle) $ Bullet $ map (, Nothing) (versionList getDoxRef noSwiftJlEx)]
     where
@@ -230,10 +231,11 @@ getSRSRef path format ex = makeURI refUID (getSRSPath path format ex) $ shortnam
 getSRSPath :: FilePath -> Format -> String -> FilePath
 getSRSPath path format ex = path ++ map toLower ex ++ "/SRS/" ++ show format ++ "/" ++ sufx format
   where
-    sufx MDBook = "book"
-    sufx HTML   = ex ++ "_SRS.html"
-    sufx TeX    = ex ++ "_SRS.pdf"
-    sufx _      = error "You can only get paths for TeX/HTML/MDBook."
+    sufx MDBook  = "book"
+    sufx HTML    = ex ++ "_SRS.html"
+    sufx TeX     = ex ++ "_SRS.pdf"
+    sufx Jupyter = ex ++ "_SRS.html"
+    sufx Plain   = error "Plain SRS display is not supported." 
 
 -- | Get the file paths for generated code and doxygen locations.
 getCodePath, getDoxPath :: FilePath -> String -> String -> FilePath
@@ -250,6 +252,7 @@ exampleRefs codePth srsDoxPth =
   map (getSRSRef srsDoxPth HTML . getAbrv) (examples codePth srsDoxPth) ++ 
   map (getSRSRef srsDoxPth TeX . getAbrv) (examples codePth srsDoxPth) ++ 
   map (getSRSRef srsDoxPth MDBook . getAbrv) (examples codePth srsDoxPth) ++ 
+  map (getSRSRef srsDoxPth Jupyter . getAbrv) (examples codePth srsDoxPth) ++ 
   map buildDrasilExSrcRef (examples codePth srsDoxPth)
 
 -- | Helpers to pull code and doxygen references from an example.

code/scripts/prepare_deployment.sh

@@ -93,6 +93,7 @@ copy_examples() {
       mkdir -p "$target_srs_dir/PDF"
       mkdir -p "$target_srs_dir/HTML"
       mkdir -p "$target_srs_dir/mdBook"
+      mkdir -p "$target_srs_dir/Jupyter"
       if [ -d "$example/SRS/PDF" ]; then
         cp "$example/SRS/PDF/"*.pdf "$target_srs_dir/PDF"
       fi
@@ -102,6 +103,9 @@ copy_examples() {
       if [ -d "$example/SRS/mdBook" ]; then
         cp -r "$example/SRS/mdBook/book/" "$target_srs_dir/mdBook"
       fi
+      if [ -d "$example/SRS/Jupyter" ]; then
+        cp -r "$example/SRS/Jupyter/"*.html "$target_srs_dir/Jupyter"
+      fi
       if [ -d "$example/src" ]; then
         mkdir -p "$EXAMPLE_DEST$example_name/$DOX_DEST"
         for lang in "$example/src/"*; do

wiki/New-Workspace-Setup.md

@@ -14,6 +14,7 @@ Optionally, some functions will be limited without:
 1. [Doxygen](#doxygen)
 2. [ShellCheck](#shellcheck)
 3. [mdBook](#mdBook)
+4. [Jupyter](#jupyter)
 
 **Notes**: 
 1. It is [**recommended**](https://github.com/JacquesCarette/Drasil/issues/2913#issuecomment-987300398) for Windows users to install the following tools using Linux on Windows/Windows WSL. If you choose to install using Windows WSL, you can safely ignore all Windows installation notes (except for that regarding Unicode support), and follow the instructions for Linux machines with the *apt*-package manager (e.g., Debian, Ubuntu, etc). From experience, installations with Windows WSL over native installations provide better tools, quicker installs, and an overall smoother experience.
@@ -595,5 +596,21 @@ cargo install mdbook
 
 </details>
 
+## Jupyter
+
+[Jupyter(Lab)](https://jupyter.org/) is a web-based integrated development environment for developing computational documents, well-suited for researchers and students. We do not necessarily use Jupyter ourselves in Drasil's development, but we currently generate Jupyter documents (including lesson plans) and intend to generate more.
+
+### Installation Instructions
+
+Installing Jupyter is fairly straightforward using Python's package manager, `pip`. You only need to run the following command:
+
+```
+pip install jupyter
+```
+
+Alternatively, you can use copies of Jupyter from other package managers (e.g., via Homebrew: `brew install jupyter`, via `apt`: `sudo apt-get install jupyter`, etc.). For more information, please see the official Jupyter [installation documentation](https://jupyter.org/install).
+
+To test that your installation is working, you should be able to run `jupyter --help` and see basic usage information.
+
 # Working with Drasil
-Congratulations! Now that you've successfully setup your workspace, you should move on to our [Contributer's Guide](https://github.com/JacquesCarette/Drasil/wiki/Contributor's-Guide).
+Congratulations! Now that you've successfully setup your workspace, you should move on to our [Contributer's Guide](https://github.com/JacquesCarette/Drasil/wiki/Contributor's-Guide).