Build Documentation

This document explains how to build the Sphinx documentation for the Parrot application. We will cover setting up a virtual environment (venv), installing pip and using requirements.txt, running make commands in the correct order, and finally, identifying which documents need to be pushed to the web server.

Note

Parrot is in early development, not ready for end users.

Setup Instructions

Clone the repository: First, clone the repository using this command:

git clone --recursive https://spacecruft.org/deepcrayon/parrot-wtf

Change directory into the repository: After cloning, navigate to the project’s root directory by running:
```
cd parrot-wtf
```

Install python3-venv (apt): This is required for creating a virtual environment. Run this command:

sudo apt update
sudo apt install docutils gettext python3-pip python3-venv
# To build PDFs with LaTeX
sudo apt install texlive-full xindy

Set up a virtual environment (venv): Navigate to your project’s root directory and run:
```
python3 -m venv venv
```
Activate the virtual environment: Before installing any packages, activate the virtual environment by running:
```
source venv/bin/activate
```
Use requirements.txt: This file contains a list of project dependencies. To install them using pip, run:
```
pip install -r requirements.txt
```

Install Submodules: Install other Parrot repository submodules to include their documentation.

pip install -r datasets/requirements.txt
pip install -r extension/requirements.txt
pip install -r ide/requirements.txt
pip install -r models/requirements.txt

pip install -e datasets

Building the Documentation

Clean existing build: If you have previously built the documentation, start by cleaning up the old build files with this command:
```
make clean
```
Build the HTML version of the docs: The Parrot application uses Sphinx to generate its documentation. To create the HTML version, run:
```
make html
```
Other useful ``make`` commands: There are other make commands available in the Makefile. You can view them by running:
```
make help
```

Push to Web Server

After building the documentation, you will find the HTML files in the build/html directory. These are the files that need to be uploaded to your web server.

Edit .env to set the server URL to be used by rsync, such as:

URL="parrot.wtf:/var/www/html/parrot-wtf/"

Run the following command to rsync to the server:

./scripts/rsync-parrot-wtf

This will push all the HTML files in build/html to your main server.

Note

Parrot documentation is written in English and uses AI machine translation for other languages.