Development Environment Improvements (#807)

* work on dev mode

* improve development environment instructions

* fix flake8 issue

.devcontainer/postCreateCommand.sh

@@ -8,7 +8,6 @@ echo 'export PATH="/root/.local/bin:$PATH"' > ~/.bashrc
 sudo `which poetry` config virtualenvs.create false
 sudo `which poetry` install --with dev
 python scripts/fetch_core.py
-python scripts/bundle_resources.py
 playwright install-deps
 playwright install
 # Run mypy once so that it will install any needed type stubs. After this, the VSCode extension will run it automatically.

README.md

@@ -150,7 +150,10 @@ cd pretext-cli
 Developers and contributors must install a
 version of Python that matching the requirements in `pyproject.toml`.
 
-#### Using pyenv and poetry (Mac/Linux)
+
+### Installing dependencies
+<details>
+<summary><b>Optional</b>: use pyenv as a virtual environment</summary>
 
 The `pyenv` tool for Linux automates the process of running the correct
 version of Python when working on this project (even if you have
@@ -163,65 +166,58 @@ Run the following, replacing `PYTHON_VERSION` with your desired version.
 ```
 pyenv install PYTHON_VERSION
 ```
+#### Steps on Windows
 
-Then follow these instructions to install `poetry`.
+In windows, you can either use the bash shell and follow the directions above,
+or try [pyenv-win](https://github.com/pyenv-win/pyenv-win#installation). In
+the latter case, make sure to follow all the installation instructions, including
+the **Finish the installation**. Then proceed to follow the directions above to
+install a version of python matching `pyproject.toml`. Finally, you may then need
+to manually add that version of python to your path.
 
--   https://python-poetry.org/docs/#installation
-    -   Note 2022/06/21: you may ignore "This installer is deprecated". See
-        [python-poetry/poetry/issues/4128](https://github.com/python-poetry/poetry/issues/4128)
+</details>
 
-Then you should be able to install dependencies into a virtual environment
-with this command.
+<br/>
 
-```
-poetry install
-```
+The first time you set up your development environment, you should follow these steps:
 
-Before you attempt to run `pretext` locally, you must fetch a copy of the core pretext library
-and zip up templates by running
+1. Follow these instructions to install `poetry`.
 
-```
-poetry run python scripts/fetch_core.py
-poetry run python scripts/zip_templates.py
-```
+    -   https://python-poetry.org/docs/#installation
+        -   Note 2022/06/21: you may ignore "This installer is deprecated". See
+            [python-poetry/poetry/issues/4128](https://github.com/python-poetry/poetry/issues/4128)
 
-Then to use the in-development package, you can either enter a poetry shell:
+2. Install dependencies into a virtual environment with this command.
 
-```
-pretext --version # returns system version
-poetry shell
-pretext --version # returns version being developed
-exit
-pretext --version # returns system version
-```
+    ```
+    poetry install
+    ```
 
-Or use the runner (as long as you remain within the package directory):
+3. Fetch a copy of the core pretext library and bundle templates by running
+
+    ```
+    poetry run python scripts/fetch_core.py
+    ```
+
+The last command above should also be run when returning to development after some time, since the core commit you develop against might have changed.
 
-```
-pretext --version             # returns system version
-poetry run pretext --version  # returns version being developed
-```
 
-If you run `echo 'alias pr="poetry run"' >> ~/.bashrc` then restart your
-shell, this becomes less of a mouthful:
+Make sure you are in a `poetry shell` during development mode so that you
+execute the development version of `pretext-cli` rather than the system-installed
+version.
 
 ```
-pretext --version     # returns system version
-pr pretext --version  # returns version being developed
+pretext --version # returns system version
+poetry shell
+pretext --version # returns version being developed
 ```
-(On Windows, in PowerShell, you get get such an alias with `Function pr {poetry run @Args}`)
 
-#### Steps on Windows
+When inside a `poetry shell` you can navegate to other folders and run pretext commands.  Doing so will use the current development environment version of pretext.
 
-In windows, you can either use the bash shell and follow the directions above,
-or try [pyenv-win](https://github.com/pyenv-win/pyenv-win#installation). In
-the latter case, make sure to follow all the installation instructions, including
-the **Finish the installation**. Then proceed to follow the directions above to
-install a version of python matching `pyproject.toml`. Finally, you may then need
-to manually add that version of python to your path.
 
 ### Updating dependencies
-
+<details>
+<summary>Show instructions</summary>
 To add dependencies for the package, run
 
 ```
@@ -233,38 +229,14 @@ If someone else has added a dependency:
 ```
 poetry install
 ```
+</details>
 
-### Syncing untracked updates
 
-Updates to certain files tracked to the repository will
-need to be rebuilt by each user when pulled from GitHub.
+### Using a local copy of `PreTeXtBook/pretext`
 
-The file `pretext/__init__.py` tracks the upstream
-commit of core PreTeXt XSL/Python code we're developing against
-(from `PreTeXtBook/pretext`).
-To fetch these updates from upstream, run:
+See [docs/core_development.md](docs/core_development.md).
 
-```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
-```
 
 ### Formatting code before a commit
 

docs/core_development.md

@@ -15,13 +15,16 @@ 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 commands:
+To install the CLI from source, we follow the same instructions as in the development section of the README.
+
+<details>
+<summary>Show instructions</summary>
+First, navigate to the pretext-cli directory and install the CLI with the following commands:
 
 ```bash
 cd pretext-cli
 poetry install
 python ./scripts/fetch_core.py
-python ./scripts/bundle_resources.py
 ```
 
 You should now be able to test that everything worked by running the following commands:
@@ -38,6 +41,7 @@ poetry shell
 ```
 
 Now when you run `pretext --version` you should get the version installed with poetry.
+</details>
 
 ## Linking the core resources
 

scripts/build_package.py

@@ -1,6 +1,5 @@
 import subprocess
 import fetch_core
-import bundle_resources
 
 
 def main() -> None:
@@ -10,7 +9,7 @@ def main() -> None:
 
     # ensure up-to-date "static" resources
     fetch_core.main()
-    bundle_resources.main()
+    # bundle_resources.main() not needed; now part of fetch_core.main()
 
     # Build package
     subprocess.run(["poetry", "build"], shell=True)

scripts/fetch_core.py

@@ -6,7 +6,9 @@
 import zipfile
 
 from pretext import CORE_COMMIT
-from scripts import utils
+import utils
+
+import bundle_resources
 
 
 def main() -> None:
@@ -57,6 +59,8 @@ def main() -> None:
                             file_path, arcname=os.path.relpath(file_path, tmpdirname)
                         )
     print("Successfully updated core PreTeXtBook/pretext resources from GitHub.")
+    bundle_resources.main()
+    print("Successfully bundled core PreTeXtBook/pretext resources.")
 
 
 if __name__ == "__main__":