119 lines
3.3 KiB
ReStructuredText
119 lines
3.3 KiB
ReStructuredText
|
|
.. # Jeff Moe with Parrot and Phind-CodeLlama-34B-v2_q8.gguf
|
|
.. _parrot_sphinx_documentation:
|
|
|
|
===================
|
|
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.
|
|
|
|
.. _parrot_sphinx_documentation_setup:
|
|
|
|
.. note:: Parrot is in early development, not ready for end users.
|
|
|
|
Setup Instructions
|
|
------------------
|
|
|
|
1. **Clone the repository**: First, clone the repository using this command:
|
|
|
|
.. code-block:: bash
|
|
|
|
git clone --recursive https://spacecruft.org/deepcrayon/parrot-wtf
|
|
|
|
2. **Change directory into the repository**: After cloning, navigate to the project's root directory by running:
|
|
|
|
.. code-block:: bash
|
|
|
|
cd parrot-wtf
|
|
|
|
3. **Install python3-venv (apt):** This is required for creating a virtual environment. Run this command:
|
|
|
|
.. code-block:: bash
|
|
|
|
sudo apt update
|
|
sudo apt install docutils gettext python3-pip python3-venv
|
|
# To build PDFs with LaTeX
|
|
sudo apt install texlive-full xindy
|
|
|
|
|
|
4. **Set up a virtual environment (venv):** Navigate to your project's root directory and run:
|
|
|
|
.. code-block:: bash
|
|
|
|
python3 -m venv venv
|
|
|
|
5. **Activate the virtual environment:** Before installing any packages, activate the virtual environment by running:
|
|
|
|
.. code-block:: bash
|
|
|
|
source venv/bin/activate
|
|
|
|
6. **Use requirements.txt:** This file contains a list of project dependencies. To install them using pip, run:
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install -r requirements.txt
|
|
|
|
7. **Install Submodules:** Install other Parrot repository submodules to include their documentation.
|
|
|
|
.. code-block:: bash
|
|
|
|
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
|
|
---------------------------
|
|
|
|
1. **Clean existing build:** If you have previously built the documentation, start by cleaning up the old build files with this command:
|
|
|
|
.. code-block:: bash
|
|
|
|
make clean
|
|
|
|
2. **Build the HTML version of the docs:** The Parrot application uses Sphinx to generate its documentation. To create the HTML version, run:
|
|
|
|
.. code-block:: bash
|
|
|
|
make html
|
|
|
|
3. **Other useful ``make`` commands:** There are other ``make`` commands available in the ``Makefile``. You can view them by running:
|
|
|
|
.. code-block:: bash
|
|
|
|
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:
|
|
|
|
.. code:: bash
|
|
|
|
URL="parrot.wtf:/var/www/html/parrot-wtf/"
|
|
|
|
|
|
Run the following command to ``rsync`` to the server:
|
|
|
|
.. code:: bash
|
|
|
|
./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.
|
|
|