1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
|
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 20 Oct 2025 10:15:38 +0000
Subject: doc: enable parallel Sphinx builds; silence edit_on_github
Mark the custom edit_on_github extension as safe for parallel
reading/writing and forward GNU make's -j to sphinx-build. This removes
the Sphinx warning and allows true parallel docs builds.
Changes
- doc/source/_ext/edit_on_github.py: setup() now returns
parallel_read_safe=True and parallel_write_safe=True (plus version).
- doc/Makefile: if SPHINXOPTS lacks -j, propagate -jN from MAKEFLAGS to
sphinx-build. Bare "-j" maps to "-j auto". Respects explicit -j in
SPHINXOPTS.
Fixes: https://github.com/rsyslog/rsyslog/issues/6254
Co-authored-by: alorbach <alorbach@adiscon.com>
(cherry picked from commit 81eabd3cb3e358bffcb2e648fcd0102e62660547)
---
doc/Makefile | 13 ++++++++++++-
doc/source/_ext/edit_on_github.py | 8 ++++++++
2 files changed, 20 insertions(+), 1 deletion(-)
diff --git a/doc/Makefile b/doc/Makefile
index 9c8d292..4164bfd 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,32 +1,43 @@
# Makefile for rsyslog-doc
#
# You can set these variables from the command line.
-SPHINXOPTS ?=
+SPHINXOPTS := $(SPHINXOPTS)
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
+# Function to add parallel jobs from MAKEFLAGS to SPHINXOPTS
+define add_parallel_jobs
+ $(eval SPHINXOPTS += $(if $(filter -j%,$(SPHINXOPTS)),,$(filter -j%,$(MAKEFLAGS))))
+endef
+
.PHONY: help clean html singlehtml json alljson
help:
+ @$(call add_parallel_jobs)
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
clean:
rm -rf "$(BUILDDIR)"
html:
+ @$(call add_parallel_jobs)
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
singlehtml: # -t minimal_build triggers stripped-down config in conf.py
+ @$(call add_parallel_jobs)
@$(SPHINXBUILD) -M singlehtml "$(SOURCEDIR)" "$(BUILDDIR)" -t minimal_build $(SPHINXOPTS) -D rst_epilog='' $(O)
@echo
@echo "Build finished. The minimal single page HTML is in $(BUILDDIR)/singlehtml."
json:
+ @$(call add_parallel_jobs)
@$(SPHINXBUILD) -b json "$(SOURCEDIR)" "$(BUILDDIR)/json" $(SPHINXOPTS) $(O)
alljson: json
+ @$(call add_parallel_jobs)
@$(SPHINXBUILD) -b json "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
%:
+ @$(call add_parallel_jobs)
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/source/_ext/edit_on_github.py b/doc/source/_ext/edit_on_github.py
index a8d22c1..0c86dff 100644
--- a/doc/source/_ext/edit_on_github.py
+++ b/doc/source/_ext/edit_on_github.py
@@ -40,4 +40,12 @@ def setup(app):
app.add_config_value('edit_on_github_project', '', True)
app.add_config_value('edit_on_github_branch', 'master', True)
app.connect('html-page-context', html_page_context)
+ # Declare the extension as safe for Sphinx parallel reading/writing.
+ # This extension does not maintain global mutable state and only
+ # augments per-page rendering context, so it is safe.
+ return {
+ 'version': '1.0',
+ 'parallel_read_safe': True,
+ 'parallel_write_safe': True,
+ }
|
