🔧 build(man): add tox manpage env for regeneration

Author: gaborbernat

docs/how-to/install.rst

@@ -112,25 +112,10 @@ system ``MANPATH``. Use the ``tox man`` command to set it up:
 Building from Source
 ====================
 
-The man page is compiled from ``docs/man/tox.1.rst`` during wheel build. Package maintainers building from source can
-generate the troff file directly:
+The man page is compiled from ``docs/man/tox.1.rst`` during wheel build. To regenerate the RST source after CLI changes:
 
 .. code-block:: bash
 
-    python -c "
-    from docutils.core import publish_string
-    from pathlib import Path
-    rst = Path('docs/man/tox.1.rst').read_text()
-    content = '\n'.join(l for l in rst.splitlines() if l.strip() != ':orphan:')
-    Path('tox.1').write_bytes(publish_string(content, writer='manpage', settings_overrides={'report_level': 5}))
-    "
-    install -D -m 644 tox.1 /usr/share/man/man1/tox.1
-    gzip -9 /usr/share/man/man1/tox.1
-
-To regenerate the RST source after CLI changes:
-
-.. code-block:: bash
-
-    python tools/generate_manpage.py
+    tox run -e manpage
 
 After installation, view with ``man tox``.

docs/reference/cli.rst

@@ -51,7 +51,7 @@ environment names (``tox run -e`` lists environments from your tox configuration
 **********
 
 tox ships a Unix man page accessible via ``man tox`` (see :ref:`howto` for setup). The man page source is at
-``docs/man/tox.1.rst`` and can be regenerated from the CLI parser with ``python tools/generate_manpage.py``.
+``docs/man/tox.1.rst`` and can be regenerated from the CLI parser with ``tox run -e manpage``.
 
 **********************
  Command-line options

tox.toml

@@ -144,6 +144,14 @@ dependency_groups = [ "dev" ]
 commands = [ [ "python", "-m", "pip", "list", "--format=columns" ], [ "python", "-c", 'print(r"{env_python}")' ] ]
 uv_seed = true
 
+[env.manpage]
+description = "generate the manpage RST from the CLI parser"
+package = "editable"
+skip_install = false
+extras = [ "completion" ]
+dependency_groups = [ "docs" ]
+commands = [ [ "python", "{tox_root}/tools/generate_manpage.py" ] ]
+
 [env.fast]
 description = "fast test run for development (no integration, no slow tests, no coverage)"
 package = "editable"