Contributing to the documentation

The online documentation for trexjacket is generated by using a Python package called Sphinx to convert reStructuredText documents into html documents.

This page covers basic RST syntax (its similar to Markdown but much more powerful).

Documentation workflow

Create a virtual environment

First create a virtual environment and install the required packages:

python -m venv venv
.\venv\Scripts\activate  # on windows
pip install -r requirements.txt

Make changes to the documentation

Once you have created and activated the virtual environment, modify the rst files however you see fit. If you are creating a new section, be sure to add the file in a table of contents once you have created the standalone page, otherwise it wont show up!

The core documentation lives in the docs_src directory, and here is a high level description of its contents:

  • docs_src/index.rst: The homepage of the documentation. This document defines what shows up in the side bar as well as the homepage text.

  • docs_src/guides/: All pages that are guides live in this folder. Each guide has its own subfolder to keep things organized.

  • docs_src/guides/index.rst: This file controls the homepage of the guides section. This document defines the subheadings within the “How-to” section.

Example: adding a new tutorial

If you’d like to add a new tutorial to the documentation:

  1. Add a directory under docs_src/tutorials with a descriptive name.

  2. Add the rst for your tutorial in the directory you created in the previous step.

  3. Add your newly created tutorial to the navigation bar by adding its filename to the list found in the docs_src/tutorials/index.rst file.

Preview your changes

Always build and preview the documentation locally before submitting for review. To create the documentation locally use these commands:

cd docs_src
sphinx-build . _build

The sphinx-build command creates the html documentation pages in the _build directory. To preview the documentation, navigate to the path of the index.html page in the _build directory.

In VSCode you can find the path by right clicking index.html and selecting “Copy path”. Paste the path into your browser and you should see the documentation.

Create a PR

Once you have previewed your changes locally and are happy with how they are rendered, open a PR in the repo.