Skip to content

How to work on the documentation

Documentation is the key to this business! It has to be friendly and consistent. We have public and staff documention websites, both of which work the same way. We suggest new starters in a technical role first get to the point where they can edit and run this website.

Installing and working on the docs

The docs use a software package called mkdocs, which is designed to serve websites of static documentation. It's simpler than Sphinx, Python's documentation system. But it's still a tool for developers.

Mac and Linux

  1. Install Python

    • From the website or...
    • Mac: brew install python3.10
    • Linux: sudo apt-get install python3.10

  2. Install Mercurial

    • From the website or...
    • Mac: brew install mercurial
    • Linux: sudo apt-get install mercurial

  3. Install other requirements

    • Xcode command line tools (MAC ONLY): xcode-select --install

  4. Clone the repository

    hg clone https://hg.reportlab.com/hg-otr/ot-staff-docs/

  5. Create a virtual environment

    # substitute an appropriate directory
python3.10 -m venv /path/to/open/track/venv

  6. Activate the virtual environment

    # substitute an appropriate directory
source /path/to/open/track/venv/bin/activate

  7. Install the requirements

    python -m pip install -r requirements.txt

  8. Serve the app locally

    python -m mkdocs serve

  9. Use the following lines of code in the terminal at any location on Mac or Linux to install a fresh local copy of the documentation:

    hg clone https://hg.reportlab.com/hg-otr/ot-staff-docs/
cd ot-staff-docs
virtualenv .
. bin/activate
pip install -r requirements.txt
mkdocs serve

Note for ReportLab staff

You might encounter an authorisation error when cloning the repository, as we control access by the URL, and OpenTrack staff repos are under /hg-otr/. Try using:

hg clone https://hg.reportlab.com/hg/ot-staff-docs/

Installing on Windows

(Gus/Llewellyn/Djan, suggest you summarise the steps)

Installing on Windows 10 With WSL (Ubuntu 18.04 LTS)

Windows Subsystem for Linux (WSL) is an official feature of Windows which provides a compatibility environment between the two Operating Systems. Linux programs/tools can be run inside the subsystem from its own terminal. Setup video for those who like videos. First, make sure that Windows Subsystem for Linux is an enabled feature (video shows this). Ubuntu 18.04 LTS can be install very easily from the microsoft store by searching for it. Once installed, search for ubuntu in Start Menu to open a new terminal. Pip for python 3 will need to be installed:

sudo apt install python3-pip
pip3 install virtualenv

From here, follow the 'Installing and working on the docs - Mac and Linux' guide above.

Making edits and using Mercurial

ReportLab hosts the code, and uses Mercurial for version control. This is now less popular than Git, but when the two were emerging in 2003-2004, we felt it was far easier to understand and we still do.

Assuming your work does not clash with anyone else's, here are the basic commands you need

hg pull -u    # fetch the latest code into my local directory
hg add docs/foobar.md   # tell it my local file foobar.md should be in version control
hg commit -m "my comment"   # record a snapshot right now, locally
hg push    #   send all snapshots up to the server

If your work does clash with someone (e.g. you edited the same page), you will see a warning when you push. To resolve it do

hg pull    # fetch their changes locally
hg merge   # tries to auto-splice them together
# at this point, look at the output locally and check it's sane
hg commit -m "merged"
hg push

Additional commands (from conversation between Ben and James on 14/4/22)

hg stat    # view list of files with local changes
hg diff    # view local changes within files
hg update --clean   # remove all local changes
hg rollback         # if you commit and push but get an error, rollback, pull, commit, and push again
hg mv docs/foobar1.md docs/foobar2.md # move doc from one place to another (old to new)
hg remove docs/foobar.md # removes file completely
hg forget docs/foobar.md # stops the file being tracked, stays on local copy

You can get a good idea what went on visually by looking at a graph of changes (or here for OpenTrack staff) on the web version of the repository

Publishing to the web site

To publish your pushed changes click here

Essentially anything under the docs directory will be 'built' into an HTML web site.

Adding images

Images are stored in Amazon S3 Opentrack File Repository

Images can be uploaded at the following directory Opentrack Image Repository

By using the second Opentrack Image Repository link and entering your IAM user details you can access this repository.

12-digit Account ID: 601589172507

User name: (ask for your credentials)

Password: (ask for your credentials)

Or by using the first Amazon S3 Opentrack File Repository link with the same credentials you can then use the find services feature and type in S3, clicking on the first result will give you access to the file Opentrack repository, just navigate to files.opentrack.run > live > img to view or upload to the image files.

Public Docs

Public documentation works the same way. However, there are few differences.

Clone using hg clone https://hg.reportlab.com/hg/opentrack-docs/.
For OpenTrack staff, use hg clone https://hg.reportlab.com/hg-otr/opentrack-docs/.

Publish your pushed changes here