Run sphinx-build as a module, ensures pipx compatibility

.github/workflows/test.yml

@@ -7,6 +7,36 @@ on:
     - main
 
 jobs:
+  install_tests:
+    name: Install check using pipx
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        container: ['ros:iron', 'ros:rolling']
+    container: ${{ matrix.container }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pip
+        run: apt update && apt install -y python3-pip python3-pytest
+
+      - name: Install apt dependencies
+        run: apt update && apt install -y doxygen graphviz pipx python3-sphinx
+
+      - name: Smoke test of pipx install
+        run: |
+          PATH="$HOME/.local/bin:$PATH"
+          pipx install .
+          rosdoc2 build -d tmp/docs_build -c /tmp/cross_references -o /tmp/docs_output -p test/packages/full_package
+          if [ ! -f /tmp/docs_output/full_package/index.html ]; then
+            echo "Failed to find any output from rosdoc2"
+            exit 2
+          else
+          echo "rosdoc2 ran successfully under pipx"
+          fi
+
   unit_tests:
     name: Unit Tests
     runs-on: ubuntu-latest
@@ -25,14 +55,14 @@ jobs:
     - name: Install pip
       run: apt update && apt install -y python3-pip python3-pytest
 
+    - name: Install apt dependencies
+      run: apt update && apt install -y doxygen graphviz
+
     - name: Install pip dependencies
       run: |
        python3 -m pip install -U pycodestyle flake8 flake8-blind-except flake8-builtins flake8-class-newline flake8-comprehensions flake8-deprecated flake8-docstrings flake8-import-order flake8-quotes
        python3 -m pip install .[test]
        python3 -m pip freeze
 
-    - name: Install apt dependencies
-      run: sudo apt update && sudo apt install -y doxygen graphviz
-
     - name: Run tests
       run: python3 -m pytest --verbose test

rosdoc2/verbs/build/builders/sphinx_builder.py

@@ -19,6 +19,7 @@
 import subprocess
 
 import setuptools
+from sphinx.cmd.build import main as sphinx_main
 
 from ..builder import Builder
 from ..collect_inventory_files import collect_inventory_files
@@ -550,17 +551,12 @@ def build(self, *, doc_build_folder, output_staging_directory):
         # Invoke Sphinx-build.
         sphinx_output_dir = os.path.abspath(
             os.path.join(wrapped_sphinx_directory, 'sphinx_output'))
-        cmd = [
-            'sphinx-build',
-            wrapped_sphinx_directory,
-            sphinx_output_dir,
-        ]
         logger.info(
-            f"Running Sphinx-build: '{' '.join(cmd)}' in '{wrapped_sphinx_directory}'"
+            f"Running sphinx_build with: [{wrapped_sphinx_directory}, '{sphinx_output_dir}]'"
         )
-        completed_process = subprocess.run(cmd, cwd=wrapped_sphinx_directory)
-        msg = f"Sphinx-build exited with return code '{completed_process.returncode}'"
-        if completed_process.returncode == 0:
+        returncode = sphinx_main([wrapped_sphinx_directory, sphinx_output_dir])
+        msg = f"sphinx_build exited with return code '{returncode}'"
+        if returncode == 0:
             logger.info(msg)
         else:
             raise RuntimeError(msg)