Contributing to the documentation

You might have the best software in the world - but if nobody knows how to use it, what’s the point? Documentation can always be improved - and we need need your help!

Briefcase’s documentation is written using Sphinx and reStructuredText. We aim to follow the Diataxis framework for structuring documentation.

Building Briefcase’s documentation

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.

macOSLinuxWindows

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

Build documentation locally

Once your development environment is set up, run:

macOSLinuxWindows

(venv) $ 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:

macOSLinuxWindows

(venv) $ 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

The build process will identify reStructuredText problems, but Briefcase performs some additional “lint” checks. To run the lint checks:

macOSLinuxWindows

(venv) $ 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. When adding to this list, remember:

• We prefer US spelling, with some liberties for programming-specific colloquialism (e.g., “apps”) and verbing of nouns (e.g., “scrollable”)

• Any reference to a product name should use the product’s preferred capitalization. (e.g., “macOS”, “GTK”, “pytest”, “Pygame”, “PyScript”).

• If a term is being used “as code”, then it should be quoted as a literal rather than being added to the dictionary.

Rebuilding all documentation

To force a rebuild for all of the documentation:

macOSLinuxWindows

(venv) $ 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.

What to work on?

If you’re looking for specific areas to improve, there are tickets tagged “documentation” in Briefcase’s issue tracker.

However, you don’t need to be constrained by these tickets. If you can identify a gap in Briefcase’s documentation, or an improvement that can be made, start writing! Anything that improves the experience of the end user is a welcome change.

Submitting a pull request

Before you submit a pull request, there’s a few bits of housekeeping to do. See the section on submitting a pull request in the code contribution guide for details on our submission process.