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:
Add a directory under
docs_src/tutorials
with a descriptive name.Add the
rst
for your tutorial in the directory you created in the previous step.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.