Run sphinx-autobuild via tox -e docs-live[-src]

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

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

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{/}*