1 |
python-single-r1 does not have the python_gen_any_dep function (unlike |
2 |
python-r1). This makes dependency resolution fail if an ebuild tries to |
3 |
enable doc building (using docs.eclass or distutils_enable_sphinx) while |
4 |
DISTUTILS_SINGLE_IMPL is set and/or python-single-r1 is inherited. See |
5 |
also bug: https://bugs.gentoo.org/704520 . The python_gen_cond_dep |
6 |
function should be used instead in these cases. |
7 |
|
8 |
Therefore, I propose the following small changes to docs.eclass and |
9 |
distutils-r1.eclass (in the next email), PR is open here: |
10 |
https://github.com/gentoo/gentoo/pull/19078 |
11 |
|
12 |
Best regards, |
13 |
Andrew |
14 |
|
15 |
|
16 |
From 7b3a170cfc85120f512bd8da5201ed1f59beeabe Mon Sep 17 00:00:00 2001 |
17 |
From: Andrew Ammerlaan <andrewammerlaan@××××××.net> |
18 |
Date: Sat, 16 Jan 2021 14:28:53 +0100 |
19 |
Subject: [PATCH] eclass/docs.eclass: make compatible with python-single-r1 |
20 |
|
21 |
python-single-r1 does not have the pyhton_gen_any-dep |
22 |
function, use the pyhton_gen_cond_dep instead |
23 |
|
24 |
also a much needed update to the documentation |
25 |
of this eclass. Fixed typos, and added proper |
26 |
examples. |
27 |
|
28 |
Signed-off-by: Andrew Ammerlaan <andrewammerlaan@××××××.net> |
29 |
--- |
30 |
eclass/docs.eclass | 173 +++++++++++++++++++++++++++++++++------------ |
31 |
1 file changed, 128 insertions(+), 45 deletions(-) |
32 |
|
33 |
diff --git a/eclass/docs.eclass b/eclass/docs.eclass |
34 |
index adacae4abda64..ca198faf31470 100644 |
35 |
--- a/eclass/docs.eclass |
36 |
+++ b/eclass/docs.eclass |
37 |
@@ -10,20 +10,52 @@ |
38 |
# @SUPPORTED_EAPIS: 6 7 |
39 |
# @BLURB: A simple eclass to build documentation. |
40 |
# @DESCRIPTION: |
41 |
-# A simple eclass providing functions to build documentation. |
42 |
+# A simple eclass providing basic functions and variables to build |
43 |
+# documentation. |
44 |
# |
45 |
-# Please note that docs sets RDEPEND and DEPEND unconditionally |
46 |
-# for you. |
47 |
+# Please note that this eclass appends to RDEPEND and DEPEND |
48 |
+# unconditionally for you. |
49 |
# |
50 |
# This eclass also appends "doc" to IUSE, and sets HTML_DOCS |
51 |
-# to the location of the compiled documentation |
52 |
+# to the location of the compiled documentation automatically, |
53 |
+# 'einstalldocs' will then automatically install the documentation |
54 |
+# to the correct directory. |
55 |
# |
56 |
# The aim of this eclass is to make it easy to add additional |
57 |
-# doc builders. To do this, add a <DOCS_BUILDER>-deps and |
58 |
-# <DOCS_BUILDER>-build function for your doc builder. |
59 |
+# doc builders. To do this, add a <DOCS_BUILDER>_deps and |
60 |
+# <DOCS_BUILDER>_compile function for your doc builder. |
61 |
# For python based doc builders you can use the |
62 |
# python_append_deps function to append [${PYTHON_USEDEP}] |
63 |
# automatically to additional dependencies. |
64 |
+# |
65 |
+# Example use doxygen: |
66 |
+# @CODE |
67 |
+# DOCS_BUILDER="doxygen" |
68 |
+# DOCS_DEPEND="media-gfx/imagemagick" |
69 |
+# DOCS_DIR="docs" |
70 |
+# |
71 |
+# inherit docs |
72 |
+# |
73 |
+# ... |
74 |
+# |
75 |
+# src_compile() { |
76 |
+# default |
77 |
+# docs_compile |
78 |
+# } |
79 |
+# @CODE |
80 |
+# |
81 |
+# Example use mkdocs with distutils-r1: |
82 |
+# @CODE |
83 |
+# DOCS_BUILDER="mkdocs" |
84 |
+# DOCS_DEPEND="dev-python/mkdocs-material" |
85 |
+# DOCS_DIR="doc" |
86 |
+# |
87 |
+# PYTHON_COMPAT=( python3_{7,8,9} ) |
88 |
+# |
89 |
+# inherit distutils-r1 docs |
90 |
+# |
91 |
+# ... |
92 |
+# @CODE |
93 |
|
94 |
case "${EAPI:-0}" in |
95 |
0|1|2|3|4|5) |
96 |
@@ -50,41 +82,54 @@ esac |
97 |
# Path containing the doc builder config file(s). |
98 |
# |
99 |
# For sphinx this is the location of "conf.py" |
100 |
-# For mkdocs this is the location of "mkdocs.yml" |
101 |
# |
102 |
+# For mkdocs this is the location of "mkdocs.yml" |
103 |
# Note that mkdocs.yml often does not reside |
104 |
# in the same directory as the actual doc files |
105 |
# |
106 |
+# For doxygen the default name is Doxyfile, but |
107 |
+# package may use a non-standard name. If this |
108 |
+# is the case one should set DOCS_CONFIG_NAME to |
109 |
+# the correct name |
110 |
+# |
111 |
# Defaults to ${S} |
112 |
|
113 |
# @ECLASS-VARIABLE: DOCS_DEPEND |
114 |
# @DEFAULT_UNSET |
115 |
# @PRE_INHERIT |
116 |
# @DESCRIPTION: |
117 |
-# Sets additional dependencies to build docs. |
118 |
+# Sets additional dependencies required to build the |
119 |
+# documentation. |
120 |
# For sphinx and mkdocs these dependencies should |
121 |
-# be specified without [${PYTHON_USEDEP}], this |
122 |
+# be specified *without* [${PYTHON_USEDEP}], this |
123 |
# is added by the eclass. E.g. to depend on mkdocs-material: |
124 |
# |
125 |
+# @CODE |
126 |
# DOCS_DEPEND="dev-python/mkdocs-material" |
127 |
+# @CODE |
128 |
# |
129 |
-# This eclass appends to this variable, so you can |
130 |
-# call it later in your ebuild again if necessary. |
131 |
+# This eclass appends to this variable, this makes it |
132 |
+# possible to call it later in your ebuild again if |
133 |
+# necessary. |
134 |
|
135 |
# @ECLASS-VARIABLE: DOCS_AUTODOC |
136 |
# @PRE_INHERIT |
137 |
# @DESCRIPTION: |
138 |
# Sets whether to use sphinx.ext.autodoc/mkautodoc |
139 |
-# Defaults to 1 (True) for sphinx, and 0 (False) for mkdocs |
140 |
+# Defaults to 1 (True) for sphinx, and 0 (False) for mkdocs. |
141 |
+# Not relevant for doxygen. |
142 |
|
143 |
# @ECLASS-VARIABLE: DOCS_OUTDIR |
144 |
# @DESCRIPTION: |
145 |
-# Sets where the compiled files will be put. |
146 |
-# There's no real reason to change this, but this |
147 |
-# variable is useful if you want to overwrite the HTML_DOCS |
148 |
-# added by this eclass. E.g.: |
149 |
+# Sets the directory where the documentation should |
150 |
+# be built into. There is no real reason to change this. |
151 |
+# However, this variable is useful if the package should |
152 |
+# also install other HTML files. |
153 |
# |
154 |
+# Example use: |
155 |
+# @CODE |
156 |
# HTML_DOCS=( "${yourdocs}" "${DOCS_OUTDIR}/." ) |
157 |
+# @CODE |
158 |
# |
159 |
# Defaults to ${S}/_build/html |
160 |
|
161 |
@@ -93,18 +138,19 @@ esac |
162 |
# Name of the doc builder config file. |
163 |
# |
164 |
# Only relevant for doxygen, as it allows |
165 |
-# config files with non-standard names |
166 |
+# config files with non-standard names. |
167 |
+# Does not do anything for mkdocs or sphinx. |
168 |
# |
169 |
# Defaults to Doxyfile for doxygen |
170 |
|
171 |
if [[ ! ${_DOCS} ]]; then |
172 |
|
173 |
-# For the python based DOCS_BUILDERS we need to inherit python-any-r1 |
174 |
+# For the python based DOCS_BUILDERS we need to inherit any python eclass |
175 |
case ${DOCS_BUILDER} in |
176 |
"sphinx"|"mkdocs") |
177 |
# We need the python_gen_any_dep function |
178 |
- if [[ ! ${_PYTHON_R1} && ! ${_PYTHON_ANY_R1} ]]; then |
179 |
- die "python-r1 or python-any-r1 needs to be inherited as well to use python based documentation builders" |
180 |
+ if [[ ! ${_PYTHON_R1} && ! ${_PYTHON_ANY_R1} && ! ${_PYTHON_SINGLE_R1} ]]; then |
181 |
+ die "distutils-r1, python-r1, python-single-r1 or python-any-r1 needs to be inherited to use python based documentation builders" |
182 |
fi |
183 |
;; |
184 |
"doxygen") |
185 |
@@ -119,6 +165,7 @@ case ${DOCS_BUILDER} in |
186 |
esac |
187 |
|
188 |
# @FUNCTION: python_append_dep |
189 |
+# @INTERNAL |
190 |
# @DESCRIPTION: |
191 |
# Appends [\${PYTHON_USEDEP}] to all dependencies |
192 |
# for python based DOCS_BUILDERs such as mkdocs or |
193 |
@@ -135,6 +182,7 @@ python_append_deps() { |
194 |
} |
195 |
|
196 |
# @FUNCTION: sphinx_deps |
197 |
+# @INTERNAL |
198 |
# @DESCRIPTION: |
199 |
# Sets dependencies for sphinx |
200 |
sphinx_deps() { |
201 |
@@ -146,24 +194,36 @@ sphinx_deps() { |
202 |
if [[ -n "${DOCS_DEPEND}" ]]; then |
203 |
die "${FUNCNAME}: do not set DOCS_AUTODOC to 0 if external plugins are used" |
204 |
else |
205 |
- DOCS_DEPEND="$(python_gen_any_dep " |
206 |
- dev-python/sphinx[\${PYTHON_USEDEP}]")" |
207 |
+ if [[ ${_PYTHON_SINGLE_R1} ]]; then |
208 |
+ DOCS_DEPEND="$(python_gen_cond_dep " |
209 |
+ dev-python/sphinx[\${PYTHON_USEDEP}]")" |
210 |
+ else |
211 |
+ DOCS_DEPEND="$(python_gen_any_dep " |
212 |
+ dev-python/sphinx[\${PYTHON_USEDEP}]")" |
213 |
+ fi |
214 |
fi |
215 |
elif [[ ${DOCS_AUTODOC} == 1 ]]; then |
216 |
- DOCS_DEPEND="$(python_gen_any_dep " |
217 |
- dev-python/sphinx[\${PYTHON_USEDEP}] |
218 |
- ${DOCS_DEPEND}")" |
219 |
+ if [[ ${_PYTHON_SINGLE_R1} ]]; then |
220 |
+ DOCS_DEPEND="$(python_gen_cond_dep " |
221 |
+ dev-python/sphinx[\${PYTHON_USEDEP}] |
222 |
+ ${DOCS_DEPEND}")" |
223 |
+ else |
224 |
+ DOCS_DEPEND="$(python_gen_any_dep " |
225 |
+ dev-python/sphinx[\${PYTHON_USEDEP}] |
226 |
+ ${DOCS_DEPEND}")" |
227 |
+ fi |
228 |
else |
229 |
die "${FUNCNAME}: DOCS_AUTODOC should be set to 0 or 1" |
230 |
fi |
231 |
} |
232 |
|
233 |
# @FUNCTION: sphinx_compile |
234 |
+# @INTERNAL |
235 |
# @DESCRIPTION: |
236 |
# Calls sphinx to build docs. |
237 |
# |
238 |
-# If you overwrite src_compile or python_compile_all |
239 |
-# do not call this function, call docs_compile instead |
240 |
+# If you overwrite python_compile_all do not call |
241 |
+# this function, call docs_compile instead |
242 |
sphinx_compile() { |
243 |
debug-print-function ${FUNCNAME} |
244 |
use doc || return |
245 |
@@ -190,6 +250,7 @@ sphinx_compile() { |
246 |
} |
247 |
|
248 |
# @FUNCTION: mkdocs_deps |
249 |
+# @INTERNAL |
250 |
# @DESCRIPTION: |
251 |
# Sets dependencies for mkdocs |
252 |
mkdocs_deps() { |
253 |
@@ -198,25 +259,39 @@ mkdocs_deps() { |
254 |
: ${DOCS_AUTODOC:=0} |
255 |
|
256 |
if [[ ${DOCS_AUTODOC} == 1 ]]; then |
257 |
- DOCS_DEPEND="$(python_gen_any_dep " |
258 |
- dev-python/mkdocs[\${PYTHON_USEDEP}] |
259 |
- dev-python/mkautodoc[\${PYTHON_USEDEP}] |
260 |
- ${DOCS_DEPEND}")" |
261 |
- elif [[ ${DOCS_AUTODOC} == 0 ]]; then |
262 |
- DOCS_DEPEND="$(python_gen_any_dep " |
263 |
- dev-python/mkdocs[\${PYTHON_USEDEP}] |
264 |
+ if [[ ${_PYTHON_SINGLE_R1} ]]; then |
265 |
+ DOCS_DEPEND="$(python_gen_cond_dep " |
266 |
+ dev-python/mkdocs[\${PYTHON_USEDEP}] |
267 |
+ dev-python/mkautodoc[\${PYTHON_USEDEP}] |
268 |
+ ${DOCS_DEPEND}")" |
269 |
+ else |
270 |
+ DOCS_DEPEND="$(python_gen_any_dep " |
271 |
+ dev-python/mkdocs[\${PYTHON_USEDEP}] |
272 |
+ dev-python/mkautodoc[\${PYTHON_USEDEP}] |
273 |
${DOCS_DEPEND}")" |
274 |
+ fi |
275 |
+ elif [[ ${DOCS_AUTODOC} == 0 ]]; then |
276 |
+ if [[ ${_PYTHON_SINGLE_R1} ]]; then |
277 |
+ DOCS_DEPEND="$(python_gen_cond_dep " |
278 |
+ dev-python/mkdocs[\${PYTHON_USEDEP}] |
279 |
+ ${DOCS_DEPEND}")" |
280 |
+ else |
281 |
+ DOCS_DEPEND="$(python_gen_any_dep " |
282 |
+ dev-python/mkdocs[\${PYTHON_USEDEP}] |
283 |
+ ${DOCS_DEPEND}")" |
284 |
+ fi |
285 |
else |
286 |
die "${FUNCNAME}: DOCS_AUTODOC should be set to 0 or 1" |
287 |
fi |
288 |
} |
289 |
|
290 |
# @FUNCTION: mkdocs_compile |
291 |
+# @INTERNAL |
292 |
# @DESCRIPTION: |
293 |
# Calls mkdocs to build docs. |
294 |
# |
295 |
-# If you overwrite src_compile or python_compile_all |
296 |
-# do not call this function, call docs_compile instead |
297 |
+# If you overwrite python_compile_all do not call |
298 |
+# this function, call docs_compile instead |
299 |
mkdocs_compile() { |
300 |
debug-print-function ${FUNCNAME} |
301 |
use doc || return |
302 |
@@ -236,6 +311,7 @@ mkdocs_compile() { |
303 |
} |
304 |
|
305 |
# @FUNCTION: doxygen_deps |
306 |
+# @INTERNAL |
307 |
# @DESCRIPTION: |
308 |
# Sets dependencies for doxygen |
309 |
doxygen_deps() { |
310 |
@@ -246,11 +322,9 @@ doxygen_deps() { |
311 |
} |
312 |
|
313 |
# @FUNCTION: doxygen_compile |
314 |
+# @INTERNAL |
315 |
# @DESCRIPTION: |
316 |
# Calls doxygen to build docs. |
317 |
-# |
318 |
-# If you overwrite src_compile or python_compile_all |
319 |
-# do not call this function, call docs_compile instead |
320 |
doxygen_compile() { |
321 |
debug-print-function ${FUNCNAME} |
322 |
use doc || return |
323 |
@@ -273,12 +347,21 @@ doxygen_compile() { |
324 |
# @DESCRIPTION: |
325 |
# Calls DOCS_BUILDER and sets HTML_DOCS |
326 |
# |
327 |
-# This function must be called in global scope. Take care not to |
328 |
-# overwrite the variables set by it. Has support for distutils-r1 |
329 |
-# eclass, but only if this eclass is inherited *after* |
330 |
-# distutils-r1. If you need to extend src_compile() or |
331 |
-# python_compile_all(), you can call the original implementation |
332 |
-# as docs_compile. |
333 |
+# This function must be called in src_compile. Take care not to |
334 |
+# overwrite the variables set by it. If distutils-r1 is inherited |
335 |
+# *before* this eclass, than docs_compile will be automatically |
336 |
+# added to python_compile_all() and there is no need to call |
337 |
+# it manually. Note that this function checks if USE="doc" is |
338 |
+# enabled, and if not automatically exits. Therefore, there is |
339 |
+# no need to wrap this function in a if statement. |
340 |
+# |
341 |
+# Example use: |
342 |
+# @CODE |
343 |
+# src_compile() { |
344 |
+# default |
345 |
+# docs_compile |
346 |
+# } |
347 |
+# @CODE |
348 |
docs_compile() { |
349 |
debug-print-function ${FUNCNAME} |
350 |
use doc || return |