Development

This page describes how to set up t-doc for development. It isn't necessary for creating and editing documents.

Install

• Install the required packages for your system.

• Install Node.js, include the npm package manager and make sure it's on the system PATH.

  Windows

  winget install --id OpenJS.NodeJS.LTS
  

  macOS

  Install Node.js manually or via a package manager like Homebrew

  Linux

  Install Node.js via your system's package manager.

• Install build and hatchling.

  Windows

  python -m pip install build hatchling
  

  macOS

  python -m pip install --user build hatchling
  

  Linux

  python -m pip install --user build hatchling
  

• Clone the t-doc/common repository (substitute USER with your username).

  hg clone https://USER@c-space.net/rc/hg/t-doc/common
  cd common
  

• Checkout and activate the main bookmark.

  hg checkout main
  

• Run the local server with the option --version=dev as the first argument to run.py. This installs the t-doc-common package as editable into the virtual environment _venv/dev. You may also want to use the --debug option to get full tracebacks.

  Windows

  run.py --version=dev tdoc serve --debug
  

  macOS

  ./run.py --version=dev tdoc serve --debug
  

  Linux

  ./run.py --version=dev tdoc serve --debug
  

Upgrade

• Pull missing changesets from the t-doc/common repository.

  hg pull
  

• Update to the branch head.

  hg update --check
  

• Update the generated files.

  python -m build --no-isolation --wheel
  

• If any Python dependencies need to be upgraded, delete the _venv/dev directory. It will be re-created when the local server is run the next time with --version=dev.

• Alternatively, the t-doc-common package metadata and any out-of-date dependencies can be updated in-place.

  Windows

  _venv\dev\Scripts\pip.exe install --upgrade --editable .
  

  macOS

  _venv/dev/bin/pip install --upgrade --editable .
  

  Linux

  _venv/dev/bin/pip install --upgrade --editable .