Improve core development instructions (#705)

* improve symlink_core

* update symlink core and improve action

* fix changelog

.github/workflows/deploy-stable.yml

@@ -133,7 +133,7 @@ jobs:
       - name: update changelog
         run: |
           newline="\\n## [${{ env.VERSION }}] - $(date +'%Y-%m-%d')"
-          sed "/## \[UNRELEASED\]/a\$newline" CHANGELOG.md > CHANGELOG.md.tmp
+          sed '/## \[UNRELEASED\]/a\'"$newline" CHANGELOG.md > CHANGELOG.md.tmp
           mv CHANGELOG.md.tmp CHANGELOG.md
 
       - name: commit version bump via pr

CHANGELOG.md

@@ -8,7 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Instructions: Add a subsection under `[UNRELEASED]` for additions, fixes, changes, and removals of features accompanying each PR.  When a release is made, the github action will automatically add the next version number above the unreleased changes with the date of release.
 
 ## [UNRELEASED]
-$newline
+
+## [2.3.9] - 2024-03-02
 
 ### Fixed
 

CHANGELOG.md.tmp

@@ -0,0 +1,32 @@
+# Change Log
+
+All notable changes to the PreTeXt-CLI will be documented in this file (admittedly started rather late in the game).
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Instructions: Add a subsection under `[UNRELEASED]` for additions, fixes, changes, and removals of features accompanying each PR.  When a release is made, the github action will automatically add the next version number above the unreleased changes with the date of release.
+
+## [UNRELEASED]
+testing
+
+## [2.3.9] - 2024-02-25
+
+### Fixed
+
+- Temporary hack fixes `pretext view` issues in codespaces.
+
+### Changed
+
+- `pretext view` now opens browser sooner when you are not using codespaces.
+
+## [2.3.8] - 2024-02-25
+
+### Added
+
+- Added this CHANGELOG.md file to track future changes to the PreTeXt-CLI.
+
+### Changed
+
+- Generating webwork will now continue in most cases where a single exercise is invalid, still creating a representations file.
+- Improve error message when webwork-representations file fails to build.

README.md

@@ -244,22 +244,25 @@ commit of core PreTeXt XSL/Python code we're developing against
 (from `PreTeXtBook/pretext`).
 To fetch these updates from upstream, run:
 
-```
+```bash
 poetry run python scripts/fetch_core.py
 ```
 
 If you instead want to point to a local copy of `PreTeXtBook/pretext`,
 try this instead to set up symlinks:
 
-```
+```bash
 poetry run python scripts/symlink_core.py path/to/pretext
 ```
 
+For more detailed directions on using a local copy of the core resources to develop core and CLI together, see [docs/core_development.md](docs/core_development.md).
+
+
 Updates to `templates/` must be zipped and moved into
 `pretext/templates/resources`. This is done automatically by
 running:
 
-```
+```bash
 poetry run python scripts/zip_templates.py
 ```
 

docs/core_development.md

@@ -0,0 +1,64 @@
+# Using the CLI when developing on core pretext
+
+The CLI bundles a frozen version of the core python script, as well as the corresponding support files (xsl, css, js, etc).  But because of this, it is not possible for the CLI to use a local version of the core python script.  This means that if you are developing on the core python script and want to test with the CLI, you will need to install the CLI from source.
+
+This guide will walk you through the process of installing the CLI from source and linking the core resources to your local version of the pretext repository.
+
+## Installing the CLI from source
+
+We will assume you have a local clone of the pretext repository in a directory parallel to a local clone of the pretext-cli repository.  
+
+If you don't have these yet, you can clone them with the following commands:
+
+```bash
+git clone https://github.com/PreTeXtBook/pretext-cli.git
+git clone https://github.com/PreTeXtBook/pretext.git
+```
+
+As in the development directions in the README, we will use poetry to install the CLI from source.  First, navigate to the pretext-cli directory and install the CLI with the following command:
+
+```bash
+cd pretext-cli
+poetry install
+```
+
+You should now be able to test that everything worked by running the following commands:
+
+```bash
+pretext --version # You should get the version installed with PIP
+poetry run pretext --version # You should get the newer version installed with poetry
+```
+
+At this point, it is probably easiest to start a `poetry shell` so you don't have to prefix every command with `poetry run`.
+
+```bash
+poetry shell
+```
+
+Now when you run `pretext --version` you should get the version installed with poetry.
+
+## Linking the core resources
+
+The CLI has a script `script\symlink_core.py` that will create symbolic links from the CLI's `core` directory to the core directory in the pretext repository.  This script will also create a `core` directory in the CLI's `pretext` directory and link the core resources there as well.  This is necessary because the CLI uses the core resources from the `pretext` directory, not the `core` directory. 
+
+Assuming you have the pretext and pretext-cli repositories in the same directory, you can run the following command to link the core resources:
+
+```bash
+python script/symlink_core.py
+```
+
+If you have the pretext repository elsewhere, you can specify the path to the pretext repository as an argument to the script:
+
+```bash
+python script/symlink_core.py /path/to/pretext
+```
+
+Now any changes you make the python script, xsl, css, js, or schema in the pretext repository will be reflected in the CLI (just stay in the `poetry shell`).
+
+## Unlinking the core resources
+
+To go back to using the version of core resources specified in the `CORE_COMMIT` file, you can run the following command:
+
+```bash
+python ./script/fetch_core.py
+```

scripts/symlink_core.py

@@ -4,8 +4,9 @@
 import pretext.core.resources
 
 
+# This will redirect the static resources for pretext, including the core python script, xsl, css, etc to a local directory of your choosing that contains the clone of the pretext repository. This is useful for development purposes, as it allows you to make changes to the core python script and test with the CLI as you normally would.
 def main(core_path: Path = Path("../pretext")) -> None:
-    for subdir in ["xsl", "schema", "script", "css"]:
+    for subdir in ["xsl", "schema", "script", "css", "js", "js_lib"]:
         original_path = (core_path / subdir).resolve()
         link_path = pretext.core.resources.path(subdir)
         remove_path(link_path)