How to Update the Documentation

Follow the steps below to update the documentation and publish the changes to the website.

The commands shown below were tested on Windows PowerShell. Depending on your operating system, Python installation, and terminal environment, some commands may differ slightly.

Prerequisites

Before getting started, make sure the following are installed:

Git or GitHub Desktop
Python 3.11 or newer

Clone the GitHub Repository to your computer.
Open an IDE (such as PyCharm or VS Code) and open a terminal.

Navigate to the root directory of the locally cloned repository.
Create a Python virtual environment:
```
py -m venv .venv
```
Activate the virtual environment:
```
.venv\Scripts\Activate.ps1
```

Install the required Python packages:

python -m pip install -r requirements.txt

Build the documentation:
```
sphinx-build -M html docs/source/ docs/build/
```
The generated HTML files will be located in:
```
docs/build/html
```
Make the desired documentation changes.

After making changes, rebuild the documentation using the command from Step 6 and verify that the updates appear correctly.
Commit and push the changes to GitHub.
After pushing your changes, GitHub Actions will automatically rebuild and deploy the documentation website.

You can monitor the deployment status at GitHub Actions.

Wait until the most recent workflow run completes successfully.
Once the GitHub Actions workflow completes successfully, verify that your changes appear on the live documentation website:

Birchfield Starting Guide Documentation

Depending on GitHub Pages deployment timing and browser caching, updates may take a few minutes to appear. If necessary, refresh the page.

Troubleshooting

If a command does not work, verify the following:

Python is installed correctly.
Git is installed (unless GitHub Desktop is being used).
The terminal is opened in the root directory of the repository.
The virtual environment has been activated before installing packages or building the documentation.
All required packages have been installed using:
```
python -m pip install -r requirements.txt
```

If GitHub Actions fails to deploy the website, review the workflow logs at:

GitHub Actions

The logs typically indicate which build step failed and what corrective action is needed.