Frequently asked questions

Frequently asked questions#

Installing#

How can I 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.

How can I use the previous version of t-doc?#

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 run.toml (versioned) or run.local.toml (unversioned) 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 run.toml or run.local.toml created above.

How can I use a specific version of t-doc?#

  • Check the release notes and find the version of the t-doc-common package to install, e.g. 0.62.

  • Create a text file run.toml (versioned) or run.local.toml (unversioned) at the root of the site repository, and set its content as follows (substitute 0.62 with the desired version):

    version = "0.62"

  • Start the local server. This will install and run the selected version.

  • To return to the stable version, remove the file run.toml or run.local.toml created above.

Editing#

Why does hg push fail with "push creates new remote head"?#

When hg push fails with "push creates new remote head", it means that the remote repository contains changes that aren't available locally, usually pushed by someone else. These changes must first be pulled from the remote and merged before the push can succeed. Do not use hg push --force to try and force-push the new head.

hg pull
hg merge
# Resolve conflicts if any, and check the merge result.
hg commit

It may be worth reading a Mercurial tutorial to get familiar with basic version control workflows.

Why do my changes not show up on the deployed site?#

  • Check the "Publish" status on the badge at the bottom of the left sidebar. If it is failing, click on the badge and check the logs of the failing workflow.

  • Check that the main bookmark is active and pointing to the repository head. Run:

    hg id

    The command should output the current revision, followed by tip main. If it doesn't, the bookmark must be moved to the current revision and pushed with:

    hg bookmark main
hg push -B main

Troubleshooting#

The local server fails with ERROR: run() got an unexpected keyword argument 'ssl_ctx'. How can I fix it?#

This is a temporary error due to a compatibility issue with run-stage2.py. Running the local server again while connected to the internet should fix the issue.

The local server fails to start. How can I fix it?#

  • Perform a clean install of t-doc and run the server again. If this works, you're done.

  • Roll back to the previous version of t-doc and run the server again. If this works, please report the issue, Don't forget to revert to the stable version once the issue is fixed.

  • Run the server with --debug, copy the full console output and report the issue.

How can I report an issue with t-doc?#

Contact your favorite support person by email, and provide as much relevant information as possible, including:

  • A precise description of the issue

  • The full error message, if possible with a traceback (run the command with --debug)

  • The site repository

  • The operating system running on your computer