chore: Complete conversion to pnpm

  Moves all of the markdown documentation of pnpm scripts into package.json5,
  thanks to its ability to have comments. Rmoves npm-run-all as no longer
  being used.

  Resolves #140.

Author: gwhitney

doc/working-with-pm.md

@@ -12,7 +12,7 @@ nav:
     - Contributing:
           - doc/contributing.md
           - doc/visual-studio-code-setup.md
-          - doc/working-with-pm.md
+          - package.md
     - Other Information:
           - ... | flat | doc/*.md
 docs_dir: doc
@@ -33,7 +33,7 @@ plugins:
           include_extensions: ['.png']
           merge_docs_dir: false
           semiliterate:
-              - pattern: '\.ts' # Standard in-code markup
+              - pattern: '\.(?:ts|json5)' # Standard in-code markup
                 extract:
                     start: '^\s*/\*\*+\W?md\b' # Opening like /** md
                     stop: '^\s*\*\*/\s*$' # closing **/ by itself on a line

mkdocs.yml

@@ -2,84 +2,100 @@
 # Using package manager scripts
 
 This repository is designed to work with the [pnpm](https://pnpm.io/) package
-manager, and precludes installation of packages with other package managers.
+manager, and so precludes installation of packages with other package managers.
 It also sets up a number of utility "scripts" that you can run via the package
 manager to manipulate and execute the project's code. This page documents all
 of the available scripts.
-*/
+ **/
 {
     name: 'frontscope',
     version: '0.3.0',
     scripts: {
-        'help:help': 'echo Prints a list of available scripts and a reminder about how to get more help.',
-        help: "echo Available scripts -- execute \\`pnpm help:SCRIPTNAME\\` for help on SCRIPTNAME: && (pnpm run | grep '^\\s\\s\\S' | grep -v 'help\\|only\\|postinstall\\|prepare')",
-        'help:dev': 'run-s -s help:dev:*',
-        'help:dev:1': 'echo Compiles frontscope and starts a server running it.',
-        'help:dev:2': 'echo Note the server will hot-reload the code from any',
-        'help:dev:3': 'echo source files as they change, to ease development.',
+        /** md
+### pnpm dev
+
+Compiles frontscope and starts a server running it. Note the server will
+hot-reload the code from any source files as they change, to ease development.
+The documentation pages are not available in this server.
+         **/
         dev: 'pnpm typecheck && vite',
-        'help:doc:serve': 'run-s -s help:doc:serve:*',
-        'help:doc:serve:1': "echo This is like the 'dev' script, but for the",
-        'help:doc:serve:2': 'echo embedded documentation rather than the',
-        'help:doc:serve:3': 'echo Numberscope interface itself.',
+        /** md
+### pnpm doc:serve
+
+This is like the 'dev' script, but for the embedded documentation rather
+than the Numberscope interface itself. So Numberscope visualizers will not
+be available, but the documentation pages will hot-reload as doc files are
+changed.
+         **/
         'doc:serve': '.venv/bin/mkdocs serve',
-        'help:build': 'run-s -s help:build:*',
-        'help:build:1': 'echo Compiles frontscope and minifies the result,',
-        'help:build:2': 'echo producing a bundle ready for installation',
-        'help:build:3': 'echo on a server.',
+        /** md
+### pnpm build
+
+Compiles frontscope and minifies the result, producing a bundle ready for
+preview or installation on a server.
+         **/
         build: 'pnpm typecheck && vite build && .venv/bin/mkdocs build',
-        'help:preview': 'run-s -s help:build:*',
-        'help:preview:1': 'echo Serves the most recently built files -- the',
-        'help:preview:2': "echo contents of the 'dist/' directory -- for you",
-        'help:preview:3': "echo to preview. This script differs from 'dev' in",
-        'help:preview:4': "echo that there isn't any hot module reload. It is",
-        'help:preview:5': 'echo closer to what you will run in production.',
+        /** md
+### pnpm preview
+
+Serves the most recently built files (i.e., the contents of the `dist/`
+directory) for you to preview. This script differs from 'dev' in that there
+isn't any hot module reload. On the other hand, it is closer to what you will
+run in production, and both the Numberscope interface and the documentation
+pages are available.
+         **/
         preview: 'vite preview',
-        'help:test:unit': 'echo Runs unit tests.',
+        /** md
+### pnpm test:unit
+
+Runs unit tests.
+         **/
         'test:unit': 'vitest run',
-        'help:typecheck': 'run-s -s help:typecheck:*',
-        'help:typecheck:1': 'echo Checks for TypeScript errors in both .vue',
-        'help:typecheck:2': 'echo and .ts files.',
+        /** md
+### pnpm typecheck
+
+Checks for TypeScript errors in both .vue and .ts files.
+         **/
         typecheck: 'vue-tsc --noEmit -p tsconfig.vitest.json --composite false',
-        'help:lint': 'run-s -s help:lintx:*',
-        'help:lintx:01': 'echo If you would like to format your code before you',
-        'help:lintx:02': 'echo make a commit with git -- which has hooks to do',
-        'help:lintx:03': 'echo automatic formatting -- you can call this script',
-        'help:lintx:04': "echo at any time. It runs 'prettier' and",
-        'help:lintx:05': "echo 'eslint --fix' on the project files. Note that",
-        'help:lintx:06': 'echo this operation does not simply _check_ the',
-        'help:lintx:07': 'echo formatting of your files, it _formats_ them!',
-        'help:lintx:08': 'echo At least, if possible -- there are some',
-        'help:lintx:09': 'echo formatting/code errors that it does not know how',
-        'help:lintx:10': 'echo to fix. These will simply be reported as errors.',
-        'help:lintx:11': 'echo If any such issues are present at the time of a',
-        'help:lintx:12': 'echo of a commit, presuming the standard git hooks',
-        'help:lintx:13': 'echo this project sets up are in place, the commit',
-        'help:lintx:14': 'echo will be rejected.',
+        /** md
+### pnpm lint
+
+If you would like to format your code before you make a commit with git (which
+has hooks to do automatic formatting), you can call this script at any time.
+It runs [prettier](https://prettier.io/) and `eslint --fix`
+(see https://eslint.org/) on the project files. Note that this operation does
+not simply _check_ the formatting of your files, it automatically _reformats_
+them when it finds problems!
+
+At least, if possible -- there are some formatting/code errors that it does
+not know how to fix. These will simply be reported as errors. If any such
+issues are present at the time of a commit, presuming the standard git hooks
+this project sets up are in place, the commit will be rejected.
+         **/
         lint: 'prettier-eslint --write "**/*.*" && pnpm lint:check',
-        'help:lint:check': 'run-s -s help:lint:check:*',
-        'help:lint:check:01': "echo This is like the 'lint' script but only",
-        'help:lint:check:02': 'echo reports problems; does not modify any of',
-        'help:lint:check:03': 'echo your source files. Note that this script',
-        'help:lint:check:04': 'echo might not report any errors but then a run',
-        'help:lint:check:05': "echo of the 'lint' script might modify files.",
-        'help:lint:check:06': "echo That can happen because 'prettier' does not",
-        'help:lint:check:07': "echo have a 'diagnostic' mode in which it",
-        'help:lint:check:08': 'echo reports discrepancies with its preferred',
-        'help:lint:check:09': 'echo formatting, while some formatting not',
-        'help:lint:check:10': 'echo preferred by prettier is nevertheless',
-        'help:lint:check:11': 'echo acceptable to eslint.',
+        /** md
+### pnpm lint:check
+
+This is like the 'lint' script but only reports problems; it does not modify
+any of your source files. Note that this script might not report any errors
+but then a run of the 'lint' script might modify files. That behavior can
+occur because 'prettier' does not have a 'diagnostic' mode in which it
+reports discrepancies with its preferred formatting, while some formatting
+_not_ preferred by prettier is nevertheless acceptable to eslint.
+         **/
         'lint:check': 'eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --ignore-path .gitignore',
-        'help:lint:list': 'run-s -s help:lint:list:*',
-        'help:lint:list:1': "echo This is like the 'lint' script but only",
-        'help:lint:list:2': 'echo _lists_ the files that would be changed.',
-        'help:lint:list:3': 'echo It does not modify any source files or report',
-        'help:lint:list:4': 'echo what the problems were or report any problems',
-        'help:lint:list:5': 'echo that the tools do not know how to fix.',
+        /** md
+### pnpm lint:list
+
+This is like the 'lint' script but only _lists_ the files that would be
+changed. It does not modify any source files or report what the problems
+were or report any problems that the tools do not know how to fix.
+          **/
         'lint:list': 'prettier-eslint --list-different "**/*.*"',
-        'help:lint:staged': 'echo Only for internal use in the pre-commit hook.',
+        // Nothing below here is "advertised" for command-line use
+        // The following is only for internal use in the pre-commit hook:
         'lint:staged': 'lint-staged',
-        '//only lifecycle scripts below here': 'echo',
+        // And the remainder are life-cycle scripts:
         prepare: 'husky install',
         preinstall: 'npx only-allow pnpm',
         postinstall: 'python3 -m venv .venv && .venv/bin/pip install -U pip && .venv/bin/pip install -r requirements.txt',
@@ -107,7 +123,6 @@ of the available scripts.
         jsdom: '^19.0.0',
         'lint-staged': '^13.0.3',
         mathjs: '^10.5.3',
-        'npm-run-all': '^4.1.5',
         prettier: '^2.7.1',
         'prettier-eslint': '^15.0.1',
         'prettier-eslint-cli': '^6.0.1',