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
Enchant can be installed as a system package:
Ubuntu 20.04+ / Debian 10+
$ sudo apt update
$ sudo apt 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.
Build documentation locally#
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.
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
(venv) $ tox -e docs-lint
(venv) C:\...>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
(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.
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.