================================= 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 ================================== .. Docs are always built on Python 3.12. See also the RTD and tox config. To build Briefcase's documentation, start by ensuring you :ref:`have the prerequisites `, and then :ref:`set up a development environment ` (or, for a more detailed explanation of dev environment setup, :ref:`start here `).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. .. tabs:: .. group-tab:: macOS Enchant can be installed using `Homebrew `__: .. code-block:: console (venv) $ brew install enchant If you're on an Apple Silicon machine (M-series), you'll also need to manually set the location of the Enchant library: .. code-block:: console (venv) $ export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.2.dylib .. group-tab:: Linux Enchant can be installed as a system package: **Ubuntu / Debian** .. code-block:: console $ sudo apt update $ sudo apt install enchant-2 **Fedora** .. code-block:: console $ sudo dnf install enchant **Arch / Manjaro** .. code-block:: console $ sudo pacman -Syu enchant **OpenSUSE Tumbleweed** .. code-block:: console $ sudo zypper install enchant .. group-tab:: Windows Enchant is installed automatically when you set up your development environment. Build documentation locally --------------------------- Once your development environment is set up, run: .. tabs:: .. group-tab:: macOS .. code-block:: console (venv) $ tox -e docs .. group-tab:: Linux .. code-block:: console (venv) $ tox -e docs .. group-tab:: Windows .. code-block:: doscon (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: .. tabs:: .. group-tab:: macOS .. code-block:: console (venv) $ tox -e docs-live .. group-tab:: Linux .. code-block:: console (venv) $ tox -e docs-live .. group-tab:: Windows .. code-block:: doscon (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 Briefcase source code, you'll need to use the ``docs-live-src`` target to build docs: .. tabs:: .. group-tab:: macOS .. code-block:: console (venv) $ tox -e docs-live-src .. group-tab:: Linux .. code-block:: console (venv) $ tox -e docs-live-src .. group-tab:: Windows .. code-block:: doscon (venv) C:\...>tox -e docs-live-src This behaves the same as ``docs-live``, but will also monitor any changes to the ``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 Briefcase performs some additional "lint" checks. To run the lint checks: .. tabs:: .. group-tab:: macOS .. code-block:: console (venv) $ tox -e docs-lint .. group-tab:: Linux .. code-block:: console (venv) $ tox -e docs-lint .. group-tab:: Windows .. code-block:: doscon (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. 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: .. tabs:: .. group-tab:: macOS .. code-block:: console (venv) $ tox -e docs-all .. group-tab:: Linux .. code-block:: console (venv) $ tox -e docs-all .. group-tab:: Windows .. code-block:: doscon (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 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 :ref:`code contribution guide ` for details on our submission process.