diff --git a/changes/2400.misc.rst b/changes/2400.misc.rst new file mode 100644 index 0000000000..7aa4d834bf --- /dev/null +++ b/changes/2400.misc.rst @@ -0,0 +1 @@ +The ``sphinx-autobuild`` tool can now be invoked via ``tox -e docs-live`` and ``tox -e docs-live-src``. diff --git a/docs/how-to/contribute-docs.rst b/docs/how-to/contribute-docs.rst index 1654c5df5d..4ab897fa7e 100644 --- a/docs/how-to/contribute-docs.rst +++ b/docs/how-to/contribute-docs.rst @@ -92,6 +92,65 @@ Once your development environment is set up, run: 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: + +.. 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 Toga 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 +``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 --------------------- diff --git a/tox.ini b/tox.ini index 74d3135ea8..711763a62e 100644 --- a/tox.ini +++ b/tox.ini @@ -16,60 +16,56 @@ allowlist_externals = bash commands = # TOGA_INSTALL_COMMAND is set to a bash command by the CI workflow. - {env:TOGA_INSTALL_COMMAND:python -m pip install .[dev] ../dummy} + {env:TOGA_INSTALL_COMMAND:python -m pip install .[dev] {tox_root}{/}dummy} {env:test_command_prefix:} coverage run -m pytest -vv {posargs} coverage combine - coverage report --rcfile ../pyproject.toml + coverage report --rcfile {tox_root}{/}pyproject.toml -[testenv:towncrier-check] -skip_install = True -deps = - {[testenv:towncrier]deps} -commands = - python -m towncrier.check --compare-with origin/main - -[testenv:towncrier] +[testenv:towncrier{,-check}] skip_install = True deps = towncrier ~= 22.8 - ./core + {tox_root}{/}core commands = - towncrier {posargs} + check : python -m towncrier.check --compare-with origin/main + !check : python -m towncrier {posargs} [docs] -build_dir = _build -# -W: make warnings into errors -# --keep-going: continue on errors -# -j: run with multiple processes -sphinx_args = -W --keep-going -j auto -# -v: verbose logging -# -E: force rebuild of environment -# -T: print traceback on error -# -a: read/parse all files -# -d: use tox's temp dir for caching -sphinx_args_extra = {[docs]sphinx_args} -v -E -T -a -d {envtmpdir}/doctrees +docs_dir = {tox_root}{/}docs +build_dir = {[docs]docs_dir}{/}_build +# replace when Sphinx>=7.3 and Python 3.8 is dropped: +# -T => --show-traceback +# -W => --fail-on-warning +# -b => --builder +# -v => --verbose +# -a => --write-all +# -E => --fresh-env +sphinx_args = -T -W --keep-going --jobs auto -[testenv:docs{,-lint,-all}] +[testenv:docs{,-lint,-all,-live,-live-src}] skip_install = True -change_dir = docs deps = - ./core[docs] + # editable install so docstrings can be updated for 'all' and 'live' + -e {tox_root}{/}core[docs] passenv = # On macOS M1, you need to manually set the location of the PyEnchant # library: # export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.2.dylib PYENCHANT_LIBRARY_PATH commands = - !lint-!all : python -m sphinx {[docs]sphinx_args} -b html . {[docs]build_dir}/html - lint : python -m sphinx {[docs]sphinx_args_extra} -b spelling . {[docs]build_dir}/spell - lint : python -m sphinx {[docs]sphinx_args_extra} -b linkcheck . {[docs]build_dir}/links - all : python -m sphinx {[docs]sphinx_args_extra} -b html . {[docs]build_dir}/html + !lint-!all-!live : python -m sphinx {[docs]sphinx_args} {posargs} -b html {[docs]docs_dir} {[docs]build_dir}{/}html + lint : python -m sphinx {[docs]sphinx_args} {posargs} -b spelling {[docs]docs_dir} {[docs]build_dir}{/}spell + lint : python -m sphinx {[docs]sphinx_args} {posargs} -b linkcheck {[docs]docs_dir} {[docs]build_dir}{/}links + all : python -m sphinx {[docs]sphinx_args} {posargs} -v -a -E -b html {[docs]docs_dir} {[docs]build_dir}{/}html + live-!src : sphinx-autobuild {[docs]sphinx_args} {posargs} -b html {[docs]docs_dir} {[docs]build_dir}{/}live + live-src : sphinx-autobuild {[docs]sphinx_args} {posargs} -a -E --watch {tox_root}{/}core{/}src{/}toga -b html {[docs]docs_dir} {[docs]build_dir}{/}live [testenv:package] skip_install = True +passenv = FORCE_COLOR deps = build==1.0.3 twine==4.0.2 commands = python -m build {posargs} - python -m twine check {posargs}/dist/* + python -m twine check {posargs}{/}dist{/}*