Create & edit documents

Create & edit documents#

This page assumes a basic working knowledge of revision control with Mercurial. If you aren't familiar with the tool, the section below has some links and hints.

Clone a repository#

Documents are grouped into sites, which represent the unit of deployment. Each site is tracked as a Mercurial repository.

  • Clone the site repository with (substitute SITE with the name of the site):

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

    If the command asks for a username and password, ensure you have set up the Mercurial configuration as described in "Install".

  • Configure the site via conf.py, and optionally via tdoc.local.toml.

The typical structure of a site repository is shown below. The source files are located below the docs directory.

├── .github
│   └── workflows
│       └── publish.yml       A workflow to publish the site
├── docs
│   ├── conf.py               The Sphinx configuration
│   ├── index.md              The main index page
│   └── ...                   The source documents
├── .gitignore
├── .hgignore
├── LICENSE.txt
├── README.md
├── run.desktop               A desktop entry to run the local server on Linux
├── run.local.toml            An optional configuration for run.py
├── run.py                    An auto-installing wrapper for the CLI
└── tdoc.local.toml           An optional configuration for the CLI and API

Edit documents#

  • Run the local server.

    Double-click the file run.py in the repository root. Make sure that .py files are associated with Python by default.

    Alternatively, open a terminal at the repository root, and run:

    run.py

    Open a terminal, change to the repository root, and run:

    ./run.py

    Double-click the file run.desktop in the repository root.

    Alternatively, open a terminal, change to the repository root, and run:

    ./run.py

    The server renders the source files into HTML, and serves the site over HTTP.

    Running Sphinx
loading translations [fr]... done
making output directory... done
(...)
build succeeded.

The HTML pages are in _build\serve-8000-next\html.
Serving at <http://localhost:8000/>

  • Navigate to http://localhost:8000/ to view the generated pages.

  • Create and edit documents in the docs directory. This can be done with any plain text editor.

    • The local server watches the source files and automatically rebulids the HTML when a file changes.

    • When the build is successful, the browser automatically reloads all open pages.

    • If a build fails, the errors can be viewed in the terminal.

    • After the initial full build of all pages, the server rebuilds only pages that change. This is much faster, but can sometimes cause artifacts or failures. If this happens, restart the local server to trigger a full rebuild, and report the issue to the t-doc authors.

  • Stop the local server by clicking the button in the navigation bar, by typing Ctrl+C in the terminal, or by closing the terminal window.

  • Don't forget to commit changes frequently.

Deploy documents#

To deploy the site to tdoc.org:

  • Make sure that all changes have been committed (and that new files have been added with Mercurial).

  • Push the changes to the server.

    hg push

  • The changes should be live at https://SITE.t-doc.org/ within a few minutes.

    • If the build fails, the "Publish" badge in the left sidebar will turn red. Click the badge to view the build log, which should allow figuring out what went wrong.

Mercurial#

Many Mercurial tutorials are available on the internet; here are a few starting points.

You will need to learn basic usage of the following commands (add --help to any command to view its documentation):

  • hg clone: Clone a site repository from the remote server to a local directory.

  • hg status: Display the local state of tracked and untracked files.

  • hg diff: Display the changes against the last recorded state.

  • hg add: Add new files to be tracked in the repository.

  • hg remove: Remove files from the repository.

  • hg commit: Record changes.

  • hg push: Push recorded changes to the remote server. This also deploys the site.

  • hg pull: Fetch changes from the remote server.

  • hg merge: Merge diverging changes histories.

    • The t-doc authors must sometimes make changes to site repositories. You will need to merge these changes before pushing your own.