Simplify the documentation building (#2483)

* Simplify `docs/Makefile`
* Fix pre-commit push branch target
* Add doc-tests to GH-Actions
* Remove `/plans/install/docs`

Signed-off-by: Cristian Le <[email protected]>

.github/workflows/doc-tests.yml

@@ -0,0 +1,30 @@
+name: test-docs
+run-name: Documentation tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  doc-test:
+    name: Sphinx-${{ matrix.builder }}
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.experimental || false }}
+    strategy:
+      fail-fast: false
+      matrix:
+        builder: [ html ]
+        include:
+          # Run default html builder with warnings as error
+          - builder: html
+            args: -W
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run sphinx builder ${{ matrix.builder }}
+        run: |
+          pip install hatch
+          hatch run docs:${{ matrix.builder }} ${{ matrix.args }}

.github/workflows/pre-commit.yml

@@ -3,7 +3,7 @@ name: pre-commit
 on:
   pull_request:
   push:
-    branches: [master]
+    branches: [main]
 
 jobs:
   pre-commit:

.packit.yaml

@@ -46,7 +46,7 @@ jobs:
     tf_extra_params:
         test:
             tmt:
-                name: /plans/(features/core|features/basic|install/docs)
+                name: /plans/features/(core|basic)
 
   # Test pull requests (full)
   # Do not run extended unit tests, that plan gets its own job because

.readthedocs.yaml

@@ -1,12 +1,12 @@
 # Config for building https://tmt.readthedocs.io/
 version: 2
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
 build:
-    os: ubuntu-22.04
-    tools:
-        python: "3"
-    # Override RTD's default build commands, install hatch & delegate
-    # the rest to our Makefiles.
-    commands:
-      - cat docs/conf.py
-      - pip install hatch
-      - make BUILDDIR=$READTHEDOCS_OUTPUT docs
+  os: ubuntu-22.04
+  tools:
+    python: "3"

docs/Makefile

@@ -1,49 +1,12 @@
-# Makefile for Sphinx documentation
+# Makefile to generate additional sphinx sources
 #
 
 .DEFAULT_GOAL := help
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help generate-plugins plugins/*.rst generate-stories generate-template-filters generate-autodocs clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+.PHONY: help generate-plugins plugins/*.rst generate-stories generate-template-filters generate-autodocs clean
 
 clean:
-	rm -rf $(BUILDDIR) stories spec code/autodocs/*.rst code/template-filters.rst
-
-##
-## Building documentation
-##
-html: generate  ## Make standalone HTML files
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-latexpdf: generate  ## Make LaTeX files and run them through pdflatex
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text: generate  ## Make text files
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man: generate  ## Make manual pages
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+	rm -rf _build stories spec code/autodocs/*.rst code/template-filters.rst
+	find plugins -name "*.rst" ! -name index.rst | xargs rm -f
 
 ##
 ## Generate documentation sources from inputs

docs/conf.py

@@ -13,8 +13,13 @@
 
 import importlib
 import os
+import subprocess
 import sys
-from typing import Optional
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
 
 import tmt.utils
 
@@ -298,3 +303,15 @@ def _load_theme(
 
 # If true, show URL addresses after external links.
 # man_show_urls = False
+
+
+def generate_tmt_docs(app: Sphinx) -> None:
+    """
+    Run `make generate` to populate the auto-generated documentations
+    """
+    conf_dir = Path(app.confdir)
+    subprocess.run(["make", "generate"], cwd=conf_dir)
+
+
+def setup(app: Sphinx) -> None:
+    app.connect("builder-inited", generate_tmt_docs)

pyproject.toml

@@ -174,7 +174,10 @@ python = ["3.9", "3.11", "3.12"]
 dependencies = ["tmt[docs]"]
 
 [tool.hatch.envs.docs.scripts]
-html = "make -C {root}/docs html"
+# Note that in RTD there are a few additional flags (from RTD's default build
+# script) e.g. -E, -d, and -D. These should not affect generated documentation
+# files below, but it may be providing additional metadata for RTD to index.
+html = "sphinx-build -b html {root}/docs {root}/docs/_build {args}"
 man = [
     "cp {root}/docs/header.txt {root}/man.rst",
     "tail -n+8 docs/overview.rst >> {root}/man.rst",