Update the install and upgrade documentation.

docs/development.md

@@ -18,13 +18,7 @@ creating and editing documents.
   cd common
   ```
 
-- Enable git subrepositories.
-
-  ```{code-block} shell-session
-  echo -e '[subrepos]\ngit:allowed = true\n' >> .hg/hgrc
-  ```
-
-- Checkout the subrepositories and activate the `main` bookmark.
+- Checkout and activate the `main` bookmark.
 
   ```{code-block} shell-session
   hg checkout main

docs/edit.md

@@ -21,17 +21,18 @@ are located below the `docs` directory.
 :class: line-height-normal
 ├── .github
 │   └── workflows
-│       └── publish.yml       A workflow to publish the repository
+│       └── publish.yml         A workflow to publish the repository
 ├── docs
-│   ├── conf.py               The Sphinx configuration
-│   ├── index.md              The main index page
-│   └── ...                   The source documents
+│   ├── conf.py                 The Sphinx configuration
+│   ├── index.md                The main index page
+│   └── ...                     The source documents
 ├── .gitignore
 ├── .hgignore
 ├── LICENSE.txt
 ├── README.md
-├── serve.bat                 A script to run the local server on Windows
-└── serve.desktop             A desktop entry to run the local server on Linux
+├── [email protected]    An auto-installing wrapper for the tdoc command
+├── serve.bat                   A script to run the local server on Windows
+└── serve.desktop               A desktop entry to run the local server on Linux
 ```
 
 ## Edit documents
@@ -42,28 +43,32 @@ are located below the `docs` directory.
   :sync-group: platform
   ````{tab-item} Windows
   :sync: windows
-  Double-click the file `serve.bat` in the repository directory.
+  Double-click the file `serve.bat` in the repository root.
+
+  Alternatively, open a terminal, change to the repository root, and run:
+  ```{code-block} shell-session
+  [email protected] serve
+  ```
   ````
   ````{tab-item} macOS
   :sync: macos
-  Open a terminal, change to the repository directory, and run:
+  Open a terminal, change to the repository root, and run:
   ```{code-block} shell-session
-  tdoc serve
+  ./run-tdoc@t-doc-common.py serve
   ```
   ````
   ````{tab-item} Linux
   :sync: linux
-  Double-click the file `serve.desktop` in the repository directory.
+  Double-click the file `serve.desktop` in the repository root.
 
-  Alternatively, open a terminal, change to the repository directory, and run:
+  Alternatively, open a terminal, change to the repository root, and run:
   ```{code-block} shell-session
-  tdoc serve
+  ./run-tdoc@t-doc-common.py serve
   ```
   ````
   `````
 
-  The server renders the source files into HTML, and serves the result over
-  HTTP.
+  The server renders the source files into HTML, and serves the site over HTTP.
 
   ```{code-block} text
   Running Sphinx v8.0.2
@@ -83,7 +88,7 @@ are located below the `docs` directory.
   any plain text editor.
   - The local server watches the source files and **automatically rebulids the
   HTML** when a file changes.
-  - If a build is successful, the browser **automatically reloads** all open
+  - When the build is successful, the browser **automatically reloads** all open
     pages.
   - If a build fails, the errors can be viewed in the terminal.
 

docs/install/index.md

@@ -82,66 +82,57 @@ t-doc requires the following software to be installed:
 ## Install
 
 - Install the [required packages](#requirements).
-
-- Install the `t-doc-common` package.
-
-  `````{tab-set}
-  :sync-group: platform
-  ````{tab-item} Windows
-  :sync: windows
-  ```{code-block} shell-session
-  python -m pip install t-doc-common
-  ```
-  ````
-  ````{tab-item} macOS
-  :sync: macos
-  ```{code-block} shell-session
-  python -m pip install --user t-doc-common
-  ```
-  You may have to add `$HOME/.local/bin` to your `PATH`.
-  ````
-  ````{tab-item} Linux
-  :sync: linux
-  ```{code-block} shell-session
-  python -m pip install --user t-doc-common
-  ```
-  You may have to add `$HOME/.local/bin` to your `PATH`.
-  ````
-  `````
+- The `t-doc-common` package will be installed automatically when
+  [starting the local server](../edit.md#edit-documents).
 
 ## Upgrade
 
+The [local server](../edit.md#edit-documents) indicates when an upgrade is
+available.
+
 - Check the changes introduced in the new version in the
-  [release notes](release_notes).
+  [release notes](release_notes.md).
+- Restart the local server. When prompted, accept the upgrade.
 
-- Upgrade the `t-doc-common` package and any out-of-date dependencies.
+## Troubleshooting
+
+### Force a clean install
+
+If the local server refuses to start, it may be due to a broken install. To
+force a clean install of the `t-doc-common` package and its dependencies, remove
+the `_venv` directory at the root of the document repository.
+
+### Install a specific version
+
+If the latest version of the `t-doc-common` package is broken, a previous
+version of the package can be used until a fix is released.
+
+- Find the version of the `t-doc-common` package to install in the
+  [release notes](release_notes.md) (the example below uses version `0.28`).
+- Open a terminal at the root of the document repository.
+- Set the `RUN_REQUIREMENTS` environment variable to the desired version
+  specification, then run the desired command through the
+  `[email protected]` script.
 
   `````{tab-set}
   :sync-group: platform
   ````{tab-item} Windows
   :sync: windows
   ```{code-block} shell-session
-  python -m pip install --upgrade t-doc-common
-  ```
-  If you get the following error, then a
-  [local server](../edit.md#edit-documents) is running. Stop it with
-  {kbd}`Ctrl+C` or by closing its terminal window, then try again.
-  ```
-  ERROR: Could not install packages due to an OSError: [WinError 32] The process
-  cannot access the file because it is being used by another process:
-  'c:\\users\\...\\scripts\\tdoc.exe'
+  set RUN_REQUIREMENTS=t-doc-common==0.28
+  [email protected] serve
   ```
   ````
   ````{tab-item} macOS
   :sync: macos
   ```{code-block} shell-session
-  python -m pip install --user --upgrade t-doc-common
+  RUN_REQUIREMENTS=t-doc-common==0.28 ./run-tdoc@t-doc-common.py serve
   ```
   ````
   ````{tab-item} Linux
   :sync: linux
   ```{code-block} shell-session
-  python -m pip install --user --upgrade t-doc-common
+  RUN_REQUIREMENTS=t-doc-common==0.28 ./run-tdoc@t-doc-common.py serve
   ```
   ````
   `````

run-tdoc@t-doc-common.py

@@ -132,7 +132,7 @@ def want_upgrade(self):
             return False
         self.builder.out.write(f"""\
 A t-doc upgrade is available: {self.requirements} {cur} => {new}
-Would you like to upgrade (y/n)? """)
+Would you like to apply the upgrade (y/n)? """)
         resp = input().lower()
         self.builder.out.write("\n")
         return resp in ('y', 'yes', 'o', 'oui', 'j', 'ja')

tdoc/common/cli.py

@@ -25,6 +25,7 @@
 
 from . import __project__, __version__, store, util, wsgi
 
+# TODO: Remove all previous builds after a successful build
 # TODO: Implement incremental builds, by copying previous build output