This directory contains the sources for Parsec docs.

Parsec docs are written in reStructuredText (.rst) format.

Sphinx is used to build the docs in multiple output formats (such as HTML and PDF).

There are two ways to install dependencies:

• Using Poetry

  poetry install

Note You'll need extra dependencies to build PDF docs (via latexmk), see Dockerfile.

• Using Docker

  1. Build Docker image:

     docker build -t parsec-docs .

  2. Run a container:

     docker run --rm -it -v $(pwd):/data parsec-docs

     Note The current working directory must be the local path to parsec-cloud repo. It is mounted in /data in the container. This means that builds started from the container will be available in your local repo under _build directory.

Build HTML docs with:

make html

To see the list of available output formats:

make

Translations are based on Sphinx Internationalization.

1. Extract text from docs

   make gettext

2. Create/update .po files for translation

   make intl-fr

3. Translate .po files (manually or with a tool like Poedit)

4. Make sure to wrap files before commit

   make wrap

5. To build translations locally (.po -> .mo).

   make -e SPHINXOPTS="-D language='fr'" html

Note that you should only commit the .po files (not .mo files).