From d0270f5dccce7890e498023a9ea339fd6fbb18ba Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Fri, 17 Nov 2023 17:43:22 +0100 Subject: [PATCH 1/6] Simplify `docs/Makefile` - Call `make generate` inside conf.py - Remove sphinx builder make targets Signed-off-by: Cristian Le --- .readthedocs.yaml | 18 +++++++++--------- docs/Makefile | 44 +++----------------------------------------- docs/conf.py | 19 ++++++++++++++++++- pyproject.toml | 5 ++++- 4 files changed, 34 insertions(+), 52 deletions(-) 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..b2e4fa6c57 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,49 +1,11 @@ -# 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 stories spec code/autodocs/*.rst code/template-filters.rst plugins/*.rst ## ## 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/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", From 1c1fc2ae49884c48332dc55af337fdacafbc2a0b Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Mon, 6 May 2024 14:52:39 +0200 Subject: [PATCH 2/6] Fix pre-commit push branch target Signed-off-by: Cristian Le --- .github/workflows/pre-commit.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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: From 741f96c1e4abb4c6f6ca90df0c53c556c3965b8f Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Fri, 17 Nov 2023 16:48:04 +0100 Subject: [PATCH 3/6] Add doc-tests to GH-Actions Signed-off-by: Cristian Le --- .github/workflows/doc-tests.yml | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 .github/workflows/doc-tests.yml 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 }} From 362ff493e0753fa6eae69dff8bf7cd2467fe66a2 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Mon, 6 May 2024 17:42:37 +0200 Subject: [PATCH 4/6] Remove `/plans/install/docs` It is covered by github action Signed-off-by: Cristian Le --- .packit.yaml | 2 +- plans/install/docs.fmf | 17 ----------------- 2 files changed, 1 insertion(+), 18 deletions(-) delete mode 100644 plans/install/docs.fmf 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/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 From f5c140bf45c80391e13ede4a83aa4667575997e3 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Mon, 6 May 2024 19:31:34 +0200 Subject: [PATCH 5/6] glob * is too enthusiasts --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index b2e4fa6c57..67a60dd197 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,7 +5,7 @@ .PHONY: help generate-plugins plugins/*.rst generate-stories generate-template-filters generate-autodocs clean clean: - rm -rf stories spec code/autodocs/*.rst code/template-filters.rst plugins/*.rst + rm -rf stories spec code/autodocs/*.rst code/template-filters.rst plugins/!(index).rst ## ## Generate documentation sources from inputs From 6820332b2f3d3d7aa9160a5ed0c7942d9726b717 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pl=C3=ADchal?= Date: Mon, 6 May 2024 20:22:29 +0200 Subject: [PATCH 6/6] squash: Do not remove `index.rst` using `find` --- docs/Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 67a60dd197..58c91383e5 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,7 +5,8 @@ .PHONY: help generate-plugins plugins/*.rst generate-stories generate-template-filters generate-autodocs clean clean: - rm -rf stories spec code/autodocs/*.rst code/template-filters.rst plugins/!(index).rst + 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