Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Contributing to the documentation

Here are some tips for working on this documentation. You’re welcome to add more and help us out!

First of all, you should check the reStructuredText (reST) Primer to learn how to write your .rst file.

## Create a .rst file

Look at the structure and choose the best category to put your .rst file. Make sure that it is referenced in the index of the corresponding category, so it will show on in the documentation. If you have no idea how to do this, study the other index files for clues.

## Build documentation locally

To build the documentation locally, set up a development environment. However, you must have a Python 3.12 interpreter installed and available on your path (i.e., `python3.12` must start a Python 3.12 interpreter).

You’ll also need to install the Enchant spell checking library.

Enchant can be installed using Homebrew:

    (venv) $ brew install enchant

If you’re on an Apple Silicon machine, you’ll also need to manually set the location of the Enchant library:

    (venv) $ export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.2.dylib

Enchant can be installed as a system package:

Ubuntu 20.04+ / Debian 10+

    $ sudo apt-get update
    $ sudo apt-get install enchant-2

Fedora

    $ sudo dnf install enchant

Arch, Manjaro

    $ sudo pacman -Syu enchant

Enchant is installed automatically when you set up your development environment.

Once your development environment is set up, run:

    (venv) $ tox -e docs

    (venv) $ tox -e docs

    (venv) C:\...>tox -e docs

The output of the file should be in the `docs/_build/html` folder. If there are any markup problems, they’ll raise an error.

## Live documentation preview

To support rapid editing of documentation, Briefcase also has a “live preview” mode:

    (venv) $ tox -e docs-live

    (venv) $ tox -e docs-live

    (venv) C:\...>tox -e docs-live

This will build the documentation, start a web server to serve the build documentation, and watch the file system for any changes to the documentation source. If a change is detected, the documentation will be rebuilt, and any browser viewing the modified page will be automatically refreshed.

## Documentation linting

Before committing and pushing documentation updates, run linting for the documentation:

    (venv) $ tox -e docs-lint

    (venv) $ tox -e docs-lint

    (venv) C:\...>tox -e docs-lint

This will validate the documentation does not contain:

- invalid syntax and markup

- dead hyperlinks

- misspelled words

If a valid spelling of a word is identified as misspelled, then add the word to the list in `docs/spelling_wordlist`. This will add the word to the spellchecker’s dictionary.

## Rebuilding all documentation

To force a rebuild for all of the documentation:

    (venv) $ tox -e docs-all

    (venv) $ tox -e docs-all

    (venv) C:\...>tox -e docs-all

The documentation should be fully rebuilt in the `docs/_build/html` folder. If there are any markup problems, they’ll raise an error.