Contributing to Toga’s 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!

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

Building Toga’s documentation#

To build Toga’s documentation, start by setting up a development environment.

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 M1 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:

(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.

Documentation linting#

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

(venv) $ tox -e docs-lint

This will validate the documentation does not contain:

  • 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:

(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 Toga’s issue tracker.

However, you don’t need to be constrained by these tickets. If you can identify a gap in Toga’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.