Development

Contents

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.

    winget install --id OpenJS.NodeJS.LTS

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

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

  • Clone the common repository.

    hg clone -u main https://rc.t-doc.org/hg/common
cd common

  • Run the local server as usual. This installs the t-doc-common package as editable into the virtual environment _venv/dev.

Upgrade#

  • Pull missing changesets from the common repository.

    hg pull

  • Update to the branch head.

    hg update --check

  • Update the generated files.

    run.py uv build

    ./run.py uv build

    ./run.py uv build

  • 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.

Run#

Commands can be run with the development setup via its run.py script. The script runs commands within the virtual environment installed into _venv.

  • Run the local server with debug settings, as specified by the command-dev default defined in run.toml.

    run.py

    ./run.py

    ./run.py

  • Run the local server against a specific site. The command below assumes that the site checkout is in the same directory as the common checkout.

    ├── common
└── site

    cd site
..\common\run.py

    cd site
../common/run.py

    cd site
../common/run.py

  • To make the local server trigger a rebuild whenever code within common changes, add the following line to the [defaults] section of run.local.toml. This is useful when working on code related to building sites or on client-side code.

    command-dev_20 = ["--watch=../common/tdoc"]

  • To make the local server restart for each rebuild, add the following line to the [defaults] section of run.local.toml. This is useful when working on the local server itself or on API code.

    command-dev_21 = ["--restart-on-change"]

  • Create a persistent database for the local server. This requires configuring the path to the database in the [store] section of tdoc.local.toml.

    [store]
path = "tmp/store.sqlite"

    run.py tdoc store create --dev

    ./run.py tdoc store create --dev

    ./run.py tdoc store create --dev

  • Get help for tdoc sub-commands.

    run.py tdoc --help

    ./run.py tdoc --help

    ./run.py tdoc --help
Contents