devcontainer improvements (#950)

* update devcontainer and include sage install script

* switch to small devcontainer image by default

* add changes to log

* add container scripts

* add new devcontainer and install scripts

* update changelog and version

* fix installLatex script and update template readme's

* update codespace-template workflow

Author: oscarlevin

.github/workflows/codespace-template.yml

@@ -16,7 +16,7 @@ jobs:
     steps:
       - uses: actions/setup-python@v4
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Checkout codespace
         uses: actions/checkout@v4
@@ -30,11 +30,11 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install --upgrade pretext[all]
 
-      - name: pretext new book
+      - name: pretext new hello
         shell: bash
         run: |
           rm -rf *
-          python -m pretext new book -d .
+          python -m pretext new hello -d .
 
       - name: setup git config
         run: |
@@ -45,12 +45,12 @@ jobs:
       - name: restore previous files
         run: |
           git restore README.md
-          git restore GenerateAssetsHelp.md
           git restore LICENSE
 
-      - name: commit
+      - name: commit (only .devcontainer and .gitignore files)
         run: |
           # Stage the file, commit and push
-          git add .
-          git commit -m "update to latest `pretext new book`" || echo "No new commit needed"
+          git add .devcontainer/*
+          git add .gitignore
+          git commit -m "update to latest `devcontainer files`" || echo "No new commit needed"
           git push origin main || echo "All done"

CHANGELOG.md

@@ -9,10 +9,21 @@ Instructions: Add a subsection under `[Unreleased]` for additions, fixes, change
 
 ## [Unreleased]
 
+### Changed
+
+- The default devcontainer no longer includes a full LaTeX install.  If you run into trouble generating latex-images or building pdfs, see the README.md file for assistance.
+- The default devcontainer no longer includes sagemath.  If you want to build sageplot assets, see the README.md file for assistance.
+
+
 ## [2.15.2] - 2025-03-31
 
 Includes updates to core through commit: [7017d8f](https://github.com/PreTeXtBook/pretext/commit/7017d8fcc7005984ffc7fad81d0a37062a529a9d)
 
+### Fixed
+
+- Bug preventing github actions from completing deploy (internal).
+
+
 ## [2.15.1] - 2025-03-24
 
 Includes updates to core through commit: [7017d8f](https://github.com/PreTeXtBook/pretext/commit/7017d8fcc7005984ffc7fad81d0a37062a529a9d)

pretext/constants.py

@@ -226,18 +226,27 @@
     "project.ptx": Path("project.ptx"),
     "codechat_config.yaml": Path("codechat_config.yaml"),
     ".gitignore": Path(".gitignore"),
-    ".devcontainer.json": Path(".devcontainer.json"),
+    "devcontainer.json": Path(".devcontainer/devcontainer.json"),
     "requirements.txt": Path("requirements.txt"),
     "pretext-cli.yml": Path(".github", "workflows", "pretext-cli.yml"),
+    "installPretext.sh": Path(".devcontainer", "instalPretext.sh"),
+    "installPandoc.sh": Path(".devcontainer", "instalPandoc.sh"),
+    "installLatex.sh": Path(".devcontainer", "instalLatex.sh"),
+    "installSage.sh": Path(".devcontainer", "installSage.sh"),
 }
 
 DEPRECATED_PROJECT_RESOURCES = {
     "deploy.yml": Path(".github", "workflows", "deploy.yml"),
     "test-build.yml": Path(".github", "workflows", "test-build.yml"),
+    ".devcontainer.json": Path(".devcontainer.json"),
 }
 
 GIT_RESOURCES = [
     ".gitignore",
     "pretext-cli.yml",
-    ".devcontainer.json",
+    "devcontainer.json",
+    "installPretext.sh",
+    "installPandoc.sh",
+    "installLatex.sh",
+    "installSage.sh",
 ]

templates/.gitignore

@@ -1,4 +1,4 @@
-# This file was automatically generated with PreTeXt 2.15.1.
+# This file was automatically generated with PreTeXt 2.15.3.
 # If you modify this file, PreTeXt will no longer automatically update it.
 #
 # Boilerplate list of files in a PreTeXt project for git to ignore

templates/article/README.md

@@ -1,10 +1,61 @@
-# My Great Article
+# My PreTeXt Article
+
+This README was generated by running `pretext new article`.  You should feel free to edit this to describe your project.
 
 The main source file is `source/main.ptx`.  This includes the other sections of the paper.
 
 To compile the paper as an accessible website, run `pretext build web` in a terminal from any directory of this project.
 
+To preview your output, run `pretext view web`.
+
+To deploy your output to GitHub pages, run `pretext deploy`.
+
 To compile a pdf, run `pretext build print`.
 
 
-Visit <https://pretextbook.org/documentation.html> to learn more about PreTeXT.
+---
+
+Below you will find some advice for working with PreTeXt, including help with using the [PreTeXt Codespace](https://github.com/PreTeXtBook/pretext-codespace) online editor through GitHub if you don't want to install the required software on your own computer.
+
+## Learning PreTeXt
+
+See the [PreTeXt documentation](https://pretextbook.org/documentation.html) for links to a variety of resources.
+
+We also recommend browsing through the [annotated sample article](https://pretextbook.org/examples/sample-article/annotated) and [annotated sample book](https://pretextbook.org/examples/sample-book/annotated/) if you want to find examples and see the PreTeXt source for those examples quickly.
+
+## Using GitHub Codespaces
+
+GitHub Codespaces are a way to set up your whole authoring system entirely in your browser.  In case you are not already reading this inside a codespace, you can create one specifically designed for authoring in PreTeXt by using [this template](https://github.com/PreTeXtBook/pretext-codespace).
+
+### Important: how to save your files
+
+The most important thing to remember when authoring in a codespace is that you are making all your edits on a *virtual machine* off in some remote server farm.  This means there is an extra step to save your files.  You can save files in the editor (in your browser), but this just saves them to that virtual machine.  To make sure you can access these files, even if the virtual machine goes away, you need to sync them to github.com.  This is done by *committing* your changes and then *pushing* those commits (or "syncing" them).  You might see a warning when you restart your codespace that you have "uncommitted changes" -- make sure you commit them when you are done working.
+
+### Troubleshooting: Latex-images and pdfs
+
+We have tried to keep the codespace small (so it starts up quickly and doesn't eat through your monthly storage allotment), so we do not include a full TeXLive distribution.  We have tried to include most packages and fonts you are likely to need to generate images using `<latex-image>` elements, and to generate PDF print output.  However, if you run into a situation where the LaTeX gives errors about packages missing (like it cannot find a `mypackage.sty` file), here is what you should do.
+
+1. To quickly resolve the issue yourself, open a terminal (``Ctrl+Shift+` ``) and use the TeXLive Package Manager to install the missing package.  
+    1. If you know that the package is called `mypackage` then enter the following two lines:
+
+```bash
+tlmgr install mypackage
+tlmgr path add
+```
+
+    2. If you don't know the name of the package, but know it should contain `mypackage.sty`, then you can search using
+
+```bash
+tlmgr search --global --all "mypackage.sty"
+```
+
+
+2. To ensure that you don't have to repeat this step every time you recreate the codespace, add the package name to the list of installs inside the file `.devcontainer/installLatex.sh` which gets run every time a codespace is created.
+
+3. Better yet, post the name of the missing package to this [GitHub issue](https://github.com/PreTeXtBook/pretext-codespace/issues/21) and we will add it to the devcontainer.  This has the advantage that you will still get updates that other authors submit (if you edit the `installLatex.sh` file, then it won't be updated when you run `pretext update`).
+
+### Troubleshooting: sageplot images
+
+By far the largest space-hog in a PreTeXt authoring environment is SageMath, which is only required if you generate images using sageplots.  By default, SageMath is not installed in a PreTeXt codespace, but it should be easy to install if you need it.  
+
+Just open the command palette (`Ctrl+Shift+P` of `F1`) and search for "PreTeXt: Install SageMath".  This will also update the `.devcontainer/devcontainer.json` file so that the next time you create a codespace for this project, it should install automatically.

templates/book/README.md

@@ -1,3 +1,63 @@
-# My Great Book
+# My PreTeXt Book
+
+This README was generated by running `pretext new book`.  You should feel free to edit this to describe your project.
+
+
+The main source file is `source/main.ptx`.  This includes the other chapters of the book.
+
+To compile the book as an accessible website, run `pretext build web` in a terminal from any directory of this project.
+
+To preview your output, run `pretext view web`.
+
+To deploy your output to GitHub pages, run `pretext deploy`.
+
+To compile a pdf, run `pretext build print`.
+
+---
+
+Below you will find some advice for working with PreTeXt, including help with using the [PreTeXt Codespace](https://github.com/PreTeXtBook/pretext-codespace) online editor through GitHub if you don't want to install the required software on your own computer.
+
+
+## Learning PreTeXt
+
+See the [PreTeXt documentation](https://pretextbook.org/documentation.html) for links to a variety of resources.
+
+We also recommend browsing through the [annotated sample article](https://pretextbook.org/examples/sample-article/annotated) and [annotated sample book](https://pretextbook.org/examples/sample-book/annotated/) if you want to find examples and see the PreTeXt source for those examples quickly.
+
+## Using GitHub Codespaces
+
+GitHub Codespaces are a way to set up your whole authoring system entirely in your browser.  In case you are not already reading this inside a codespace, you can create one specifically designed for authoring in PreTeXt by using [this template](https://github.com/PreTeXtBook/pretext-codespace).
+
+### Important: how to save your files
+
+The most important thing to remember when authoring in a codespace is that you are making all your edits on a *virtual machine* off in some remote server farm.  This means there is an extra step to save your files.  You can save files in the editor (in your browser), but this just saves them to that virtual machine.  To make sure you can access these files, even if the virtual machine goes away, you need to sync them to github.com.  This is done by *committing* your changes and then *pushing* those commits (or "syncing" them).  You might see a warning when you restart your codespace that you have "uncommitted changes" -- make sure you commit them when you are done working.
+
+### Troubleshooting: Latex-images and pdfs
+
+We have tried to keep the codespace small (so it starts up quickly and doesn't eat through your monthly storage allotment), so we do not include a full TeXLive distribution.  We have tried to include most packages and fonts you are likely to need to generate images using `<latex-image>` elements, and to generate PDF print output.  However, if you run into a situation where the LaTeX gives errors about packages missing (like it cannot find a `mypackage.sty` file), here is what you should do.
+
+1. To quickly resolve the issue yourself, open a terminal (``Ctrl+Shift+` ``) and use the TeXLive Package Manager to install the missing package.  
+    1. If you know that the package is called `mypackage` then enter the following two lines:
+
+```bash
+tlmgr install mypackage
+tlmgr path add
+```
+
+    2. If you don't know the name of the package, but know it should contain `mypackage.sty`, then you can search using
+
+```bash
+tlmgr search --global --all "mypackage.sty"
+```
+
+
+2. To ensure that you don't have to repeat this step every time you recreate the codespace, add the package name to the list of installs inside the file `.devcontainer/installLatex.sh` which gets run every time a codespace is created.
+
+3. Better yet, post the name of the missing package to this [GitHub issue](https://github.com/PreTeXtBook/pretext-codespace/issues/21) and we will add it to the devcontainer.  This has the advantage that you will still get updates that other authors submit (if you edit the `installLatex.sh` file, then it won't be updated when you run `pretext update`).
+
+### Troubleshooting: sageplot images
+
+By far the largest space-hog in a PreTeXt authoring environment is SageMath, which is only required if you generate images using sageplots.  By default, SageMath is not installed in a PreTeXt codespace, but it should be easy to install if you need it.  
+
+Just open the command palette (`Ctrl+Shift+P` of `F1`) and search for "PreTeXt: Install SageMath".  This will also update the `.devcontainer/devcontainer.json` file so that the next time you create a codespace for this project, it should install automatically.
 
-Visit <https://pretextbook.org/documentation.html> to learn more.

templates/codechat_config.yaml

@@ -1,4 +1,4 @@
-# This file was automatically generated with PreTeXt 2.15.1.
+# This file was automatically generated with PreTeXt 2.15.3.
 # If you modify this file, PreTeXt will no longer automatically update it.
 #
 #############################################################

templates/course/README.md

@@ -1,6 +1,6 @@
-# Demo Course
+# My PreTeXt Course
 
-This is an example of how you could set up a "course" in PreTeXt.
+This README was generated by running `pretext new course`.  You should feel free to edit this to describe your project.
 
 ## Instructions
 
@@ -38,3 +38,50 @@ Look at the source files, in particular `source/acitivies.ptx` and `source/activ
 
 The use of `xpointer="/1/1/1"` is a little mysterious; we could have also used `xpoint="Activity-magic-beans"` to refer to the activity by its `xml:id`, although this would require us changing that for each included activity.
 
+
+---
+
+Below you will find some advice for working with PreTeXt, including help with using the [PreTeXt Codespace](https://github.com/PreTeXtBook/pretext-codespace) online editor through GitHub if you don't want to install the required software on your own computer.
+
+## Learning PreTeXt
+
+See the [PreTeXt documentation](https://pretextbook.org/documentation.html) for links to a variety of resources.
+
+We also recommend browsing through the [annotated sample article](https://pretextbook.org/examples/sample-article/annotated) and [annotated sample book](https://pretextbook.org/examples/sample-book/annotated/) if you want to find examples and see the PreTeXt source for those examples quickly.
+
+## Using GitHub Codespaces
+
+GitHub Codespaces are a way to set up your whole authoring system entirely in your browser.  In case you are not already reading this inside a codespace, you can create one specifically designed for authoring in PreTeXt by using [this template](https://github.com/PreTeXtBook/pretext-codespace).
+
+### Important: how to save your files
+
+The most important thing to remember when authoring in a codespace is that you are making all your edits on a *virtual machine* off in some remote server farm.  This means there is an extra step to save your files.  You can save files in the editor (in your browser), but this just saves them to that virtual machine.  To make sure you can access these files, even if the virtual machine goes away, you need to sync them to github.com.  This is done by *committing* your changes and then *pushing* those commits (or "syncing" them).  You might see a warning when you restart your codespace that you have "uncommitted changes" -- make sure you commit them when you are done working.
+
+### Troubleshooting: Latex-images and pdfs
+
+We have tried to keep the codespace small (so it starts up quickly and doesn't eat through your monthly storage allotment), so we do not include a full TeXLive distribution.  We have tried to include most packages and fonts you are likely to need to generate images using `<latex-image>` elements, and to generate PDF print output.  However, if you run into a situation where the LaTeX gives errors about packages missing (like it cannot find a `mypackage.sty` file), here is what you should do.
+
+1. To quickly resolve the issue yourself, open a terminal (``Ctrl+Shift+` ``) and use the TeXLive Package Manager to install the missing package.  
+    1. If you know that the package is called `mypackage` then enter the following two lines:
+
+```bash
+tlmgr install mypackage
+tlmgr path add
+```
+
+    2. If you don't know the name of the package, but know it should contain `mypackage.sty`, then you can search using
+
+```bash
+tlmgr search --global --all "mypackage.sty"
+```
+
+
+2. To ensure that you don't have to repeat this step every time you recreate the codespace, add the package name to the list of installs inside the file `.devcontainer/installLatex.sh` which gets run every time a codespace is created.
+
+3. Better yet, post the name of the missing package to this [GitHub issue](https://github.com/PreTeXtBook/pretext-codespace/issues/21) and we will add it to the devcontainer.  This has the advantage that you will still get updates that other authors submit (if you edit the `installLatex.sh` file, then it won't be updated when you run `pretext update`).
+
+### Troubleshooting: sageplot images
+
+By far the largest space-hog in a PreTeXt authoring environment is SageMath, which is only required if you generate images using sageplots.  By default, SageMath is not installed in a PreTeXt codespace, but it should be easy to install if you need it.  
+
+Just open the command palette (`Ctrl+Shift+P` of `F1`) and search for "PreTeXt: Install SageMath".  This will also update the `.devcontainer/devcontainer.json` file so that the next time you create a codespace for this project, it should install automatically.