Install & upgrade#

Requirements#

t-doc requires the following software to be installed:

Python 3.13
Graphviz, for graphviz directives
Mercurial, for managing source files

Windows#

Install Python.
```
winget install --id Python.Python.3.13
```
- Check that Python can be launched from the command-line, by running:
```
python
```
  If this opens the Microsoft Store, open Windows settings, search for "App execution aliases", and disable the "App Installer" entries for python.exe and python3.exe.
Install Graphviz. The installer must be run interactively and the "Add Graphviz to the system PATH for all users" option must be enabled.
```
winget install --id Graphviz.Graphviz --interactive
```
Install TortoiseHg.
```
winget install --id TortoiseHg.TortoiseHg
```
- Open the TortoiseHg settings, go to your user's global settings, then click "Edit file" and add the following to the configuration (substitute FIRST and LAST with your first and last name, and EMAIL with your email address, e.g. Joe Smith <joe@example.com>):
```
[ui]
username = FIRST LAST <EMAIL>
```
(Optional, Windows 10) Install Windows Terminal (it's already installed on Windows 11 and later).
```
winget install --id Microsoft.WindowsTerminal
```

Upgrades#

Available upgrades for these packages can be displayed and installed with winget upgrade.

winget upgrade
winget upgrade --id Python.Python.3.13
winget upgrade --id Graphviz.Graphviz
winget upgrade --id TortoiseHg.TortoiseHg
winget upgrade --id Microsoft.WindowsTerminal

macOS#

Install Python, Graphviz and Mercurial manually or via a package manager like Homebrew.

Linux#

Install Python, Graphviz and Mercurial via your system's package manager.

Install#

Install the required packages.
Everything else will be installed automatically when starting the local server.

Upgrade#

The local server indicates when an upgrade is available.

Check the changes introduced in the new version in the release notes.
Restart the local server. When prompted, accept the upgrade.

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.

Use the previous version#

If the stable version of the t-doc-common package is broken, the previous version of the package can be used until a fix is released.

Create a text file t-doc.toml at the root of the site repository, and set its content as follows:
```
version = 'previous'
```
Start the local server. This will install and run the previous version.
To return to the stable version, remove the file t-doc.toml created above.

Install a specific version#

Check the release notes and find the version of the t-doc-common package to install, e.g. 0.62.
Create a text file t-doc.toml at the root of the site repository, and set its content as follows:
```
version = '0.62'
```
Start the local server. This will install and run the selected version.
To return to the stable version, remove the file t-doc.toml created above.

Install & upgrade

Contents