[packaging] Build and include the man pages in the final PyPI package

.github/workflows/main.yml

@@ -114,6 +114,8 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Generate Wheel
+        env:
+          _RFM_BUILD_DOCS: 1
         run: |
           curl -LsSf https://astral.sh/uv/install.sh | sh
           uv build
@@ -124,6 +126,10 @@ jobs:
         run: |
           reframe -V
           reframe -l
+      - name: Check Man Pages
+        run: |
+          unzip -l dist/*.whl | grep -q 'share/man/man1/reframe\.1'
+          unzip -l dist/*.whl | grep -q 'share/man/man8/reframe\.settings\.8'
 
   docvalidation:
     runs-on: ubuntu-latest

.github/workflows/publish.yml

@@ -14,6 +14,8 @@ jobs:
         with:
           python-version: 3.14
       - name: Generate dist packages
+        env:
+          _RFM_BUILD_DOCS: 1
         run: |
           curl -LsSf https://astral.sh/uv/install.sh | sh
           ./ci-scripts/pypi_genreadme.py README.md

examples/howto/flux/settings.py

@@ -65,21 +65,5 @@
                 }
             ]
         }
-    ],
-    'general': [
-        {
-            # Flux Python bindings are supplied by the container, so reframe's
-            # default uv run method will not work, as it runs in an isolated
-            # environment. The unit tests create a venv pulling in system site
-            # packages, so here we install reframe in that venv.
-            #
-            # FIXME: Ideally, Flux bindings should be added and installed as a
-            # ReFrame extra, but this at the moment does not seem
-            # straightforward.
-            'remote_install': [
-                'cp -t . -r ../reframe ../README.md ../pyproject.toml',  # noqa: E501
-                'uv tool install .'
-            ]
-        }
     ]
 }

pyproject.toml

@@ -80,23 +80,30 @@ path = "reframe/__init__.py"
 include = [
     "/reframe/**/*.py",
     "/reframe/schemas/**/*",
-    "/docs/man/man1/reframe.1",
-    "/docs/man/man8/reframe.settings.8",
+    "/docs",
     "/examples",
     "/share/completions",
     "/tools",
     "/CONTRIBUTING.md",
     "/LICENSE",
     "/REAMDE.md",
 ]
+exclude = [
+    "/docs/_build",
+    "/docs/html",
+    "/docs/doctrees",
+    "/docs/man",
+]
 
 [tool.hatch.build.targets.wheel]
 packages = ["reframe"]
 
+[tool.hatch.build.hooks.custom]
+path = "tools/hatch_build.py"
 
 [tool.hatch.build.targets.wheel.shared-data]
 "docs/man/man1/reframe.1" = "share/man/man1/reframe.1"
-"docs/man/man8/reframe.8" = "share/man/man8/reframe.8"
+"docs/man/man8/reframe.settings.8" = "share/man/man8/reframe.settings.8"
 "examples" = "share/doc/reframe-hpc/examples"
 "share/completions/reframe.bash" = "share/bash-completion/completions/reframe"
 "share/completions/reframe.fish" = "share/fish/vendor_completions.d/reframe.fish"

reframe/frontend/autodetect.py

@@ -47,7 +47,7 @@ def __enter__(self):
         self._workdir = os.path.abspath(
             tempfile.mkdtemp(prefix='rfm.', dir=self._prefix)
         )
-        paths = ['reframe/', 'README.md', 'pyproject.toml']
+        paths = ['reframe/', 'tools/', 'README.md', 'pyproject.toml']
         use_pip = False
         custom_command = runtime.runtime().get_option(
             'general/0/remote_install'

tools/hatch_build.py

@@ -0,0 +1,30 @@
+# Copyright 2016-2026 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+import os
+import subprocess
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class ReframeBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        # Opt-in: only the release/packaging workflows need the docs built;
+        # a plain dev install should stay fast and not require Sphinx.
+        if not os.getenv('_RFM_BUILD_DOCS'):
+            return
+
+        print("Building docs...")
+
+        # --no-install-project avoids recursing into this hook: we are
+        # already building the project, so installing it here would build
+        # it again.
+        subprocess.run(
+            ["uv", "sync", "--group", "docs", "--no-install-project"],
+            check=True, cwd=self.root
+        )
+        subprocess.run(
+            ["uv", "run", "--no-sync", "make", "-C", "docs"],
+            check=True, cwd=self.root
+        )