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.
Live documentation preview¶
To support rapid editing of documentation, Toga 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.
Live preview mode will only monitor the docs
directory for changes. If you’re
updating the inline documentation associated with Toga source code, you’ll need to use
the docs-live-src
target to build docs:
(venv) $ tox -e docs-live-src
(venv) $ tox -e docs-live-src
(venv) C:\...>tox -e docs-live-src
This behaves the same as docs-live
, but will also monitor any changes to the
core/src
folder, reflecting any changes to inline documentation. However, the
rebuild process takes much longer, so you may not want to use this target unless
you’re actively editing inline documentation.
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.