diff --git a/docs/development.md b/docs/development.md index 8753922..e085c55 100644 --- a/docs/development.md +++ b/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 diff --git a/docs/edit.md b/docs/edit.md index 9a2e8f0..f869120 100644 --- a/docs/edit.md +++ b/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 +├── run-tdoc@t-doc-common.py 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 + run-tdoc@t-doc-common.py 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. diff --git a/docs/install/index.md b/docs/install/index.md index cabbdd3..6e4444a 100644 --- a/docs/install/index.md +++ b/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 + `run-tdoc@t-doc-common.py` 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 + run-tdoc@t-doc-common.py 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 ``` ```` ````` diff --git a/run-tdoc@t-doc-common.py b/run-tdoc@t-doc-common.py index d925b00..fe4a620 100755 --- a/run-tdoc@t-doc-common.py +++ b/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') diff --git a/tdoc/common/cli.py b/tdoc/common/cli.py index 7c677af..9d0d0d4 100644 --- a/tdoc/common/cli.py +++ b/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