Repository: teemtee/tmt (language: python)

Issue:
More sphinx builders
This is a continuation of #2483 to discuss and track the other sphinx builders to add
- [x] `html`: Already fully functional. #2483 tracks the warnings as fatal errors
- [ ] `linkcheck`: In #2489
- [ ] `man`: Needs some consolidations on the hatch-scripts/makefile
- [x] ~~[`spellcheck`](https://github.com/sphinx-contrib/spelling): This is a difficult one, because PyEnchant does not seem to support full-word dictionaries, e.g. `omni-present` needs to be added as `omni` in the dictionary file. This builder needs more research if there are alternatives (original contributor [switched](https://github.com/pyenchant/pyenchant/issues/293) to `skyspell`)~~ (Omitted for now until a good alternative is found. `codespell` is helping a bit)
- [ ] `doctest` + `shtest`: Requires converting the `rst` files to the corresponding directives. No usage for `doctest` found so far


Discussion / hints:

Fix patch:
diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
index 3592568b86..ad71791c0b 100644
--- a/.github/workflows/pre-commit.yml
+++ b/.github/workflows/pre-commit.yml
@@ -3,7 +3,7 @@ name: pre-commit
 on:
   pull_request:
   push:
-    branches: [master]
+    branches: [main]
 
 jobs:
   pre-commit:
diff --git a/.packit.yaml b/.packit.yaml
index 9c6f6ff503..e5aecf2d40 100644
--- a/.packit.yaml
+++ b/.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
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 27b0b6f594..57bf139739 100644
--- a/.readthedocs.yaml
+++ b/.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"
diff --git a/docs/Makefile b/docs/Makefile
index 90b57f548f..58c91383e5 100644
--- a/docs/Makefile
+++ b/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
diff --git a/docs/conf.py b/docs/conf.py
index 68cef70c60..70461062d3 100644
--- a/docs/conf.py
+++ b/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)
diff --git a/plans/install/docs.fmf b/plans/install/docs.fmf
deleted file mode 100644
index d4ace49308..0000000000
--- a/plans/install/docs.fmf
+++ /dev/null
@@ -1,17 +0,0 @@
-summary: Ensure the docs can be installed successfully
-description:
-    Make sure installing docs to the readthedocs.org site works
-    well and there is no warning displayed during the build.
-prepare:
-    how: install
-    package:
-      - make
-      - python3-pip
-      - python3-docutils
-execute:
-    script: |
-        set -ex
-        set -o pipefail
-        pip3 install .[docs]
-        make -C docs html 2>&1 | tee output
-        grep -E 'ERROR|WARNING' output && exit 1 || exit 0
diff --git a/pyproject.toml b/pyproject.toml
index ffe5da1e25..547cc01903 100644
--- a/pyproject.toml
+++ b/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",


Test patch:
diff --git a/.github/workflows/doc-tests.yml b/.github/workflows/doc-tests.yml
new file mode 100644
index 0000000000..9e3c72c248
--- /dev/null
+++ b/.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 }}