1 |
Add a helper function to easily take care of the most common |
2 |
dev-python/sphinx usage for HTML doc building. |
3 |
|
4 |
Signed-off-by: Michał Górny <mgorny@g.o> |
5 |
--- |
6 |
eclass/distutils-r1.eclass | 93 ++++++++++++++++++++++++++++++++++++++ |
7 |
1 file changed, 93 insertions(+) |
8 |
|
9 |
Changes in v2: |
10 |
- building code is split out into python-utils-r1 |
11 |
- grep -F is used |
12 |
|
13 |
diff --git a/eclass/distutils-r1.eclass b/eclass/distutils-r1.eclass |
14 |
index 63e77bf014c1..5ac061e43bcf 100644 |
15 |
--- a/eclass/distutils-r1.eclass |
16 |
+++ b/eclass/distutils-r1.eclass |
17 |
@@ -232,6 +232,99 @@ fi |
18 |
# } |
19 |
# @CODE |
20 |
|
21 |
+# @FUNCTION: distutils_enable_sphinx |
22 |
+# @USAGE: <subdir> [--no-autodoc | <plugin-pkgs>...] |
23 |
+# @DESCRIPTION: |
24 |
+# Set up IUSE, BDEPEND, python_check_deps() and python_compile_all() for |
25 |
+# building HTML docs via dev-python/sphinx. python_compile_all() will |
26 |
+# append to HTML_DOCS if docs are enabled. |
27 |
+# |
28 |
+# This helper is meant for the most common case, that is a single Sphinx |
29 |
+# subdirectory with standard layout, building and installing HTML docs |
30 |
+# behind USE=doc. It assumes it's the only consumer of the three |
31 |
+# aforementioned functions. If you need to use a custom implemention, |
32 |
+# you can't use it. |
33 |
+# |
34 |
+# If your package uses additional Sphinx plugins, they should be passed |
35 |
+# (without PYTHON_USEDEP) as <plugin-pkgs>. The function will take care |
36 |
+# of setting appropriate any-of dep and python_check_deps(). |
37 |
+# |
38 |
+# If no plugin packages are specified, the eclass will still utilize |
39 |
+# any-r1 API to support autodoc (documenting source code). |
40 |
+# If the package uses neither autodoc nor additional plugins, you should |
41 |
+# pass --no-autodoc to disable this API and simplify the resulting code. |
42 |
+# |
43 |
+# This function must be called in global scope. Take care not to |
44 |
+# overwrite the variables set by it. |
45 |
+distutils_enable_sphinx() { |
46 |
+ debug-print-function ${FUNCNAME} "${@}" |
47 |
+ [[ ${#} -ge 1 ]] || die "${FUNCNAME} takes at least one arg: <subdir>" |
48 |
+ |
49 |
+ _DISTUTILS_SPHINX_SUBDIR=${1} |
50 |
+ shift |
51 |
+ _DISTUTILS_SPHINX_PLUGINS=( "${@}" ) |
52 |
+ |
53 |
+ local deps autodoc=1 d |
54 |
+ for d; do |
55 |
+ if [[ ${d} == --no-autodoc ]]; then |
56 |
+ autodoc= |
57 |
+ else |
58 |
+ deps+=" |
59 |
+ ${d}[\${PYTHON_USEDEP}]" |
60 |
+ fi |
61 |
+ done |
62 |
+ |
63 |
+ if [[ ! ${autodoc} && -n ${deps} ]]; then |
64 |
+ die "${FUNCNAME}: do not pass --no-autodoc if external plugins are used" |
65 |
+ fi |
66 |
+ if [[ ${autodoc} ]]; then |
67 |
+ deps="$(python_gen_any_dep " |
68 |
+ dev-python/sphinx[\${PYTHON_USEDEP}] |
69 |
+ ${deps}")" |
70 |
+ |
71 |
+ python_check_deps() { |
72 |
+ use doc || return 0 |
73 |
+ local p |
74 |
+ for p in "${_DISTUTILS_SPHINX_PLUGINS[@]}"; do |
75 |
+ has_version "${p}[${PYTHON_USEDEP}]" || return 1 |
76 |
+ done |
77 |
+ } |
78 |
+ else |
79 |
+ deps="dev-python/sphinx" |
80 |
+ fi |
81 |
+ |
82 |
+ python_compile_all() { |
83 |
+ use doc || return |
84 |
+ |
85 |
+ local confpy=${_DISTUTILS_SPHINX_SUBDIR}/conf.py |
86 |
+ [[ -f ${confpy} ]] || |
87 |
+ die "${confpy} not found, distutils_enable_sphinx call wrong" |
88 |
+ |
89 |
+ if [[ ${_DISTUTILS_SPHINX_PLUGINS[0]} == --no-autodoc ]]; then |
90 |
+ if grep -F -q 'sphinx.ext.autodoc' "${confpy}"; then |
91 |
+ die "distutils_enable_sphinx: --no-autodoc passed but sphinx.ext.autodoc found in ${confpy}" |
92 |
+ fi |
93 |
+ else |
94 |
+ if ! grep -F -q 'sphinx.ext.autodoc' "${confpy}"; then |
95 |
+ die "distutils_enable_sphinx: sphinx.ext.autodoc not found in ${confpy}, pass --no-autodoc" |
96 |
+ fi |
97 |
+ fi |
98 |
+ |
99 |
+ build_sphinx "${_DISTUTILS_SPHINX_SUBDIR}" |
100 |
+ } |
101 |
+ |
102 |
+ IUSE+=" doc" |
103 |
+ if [[ ${EAPI} == [56] ]]; then |
104 |
+ DEPEND+=" doc? ( ${deps} )" |
105 |
+ else |
106 |
+ BDEPEND+=" doc? ( ${deps} )" |
107 |
+ fi |
108 |
+ |
109 |
+ # we need to ensure successful return in case we're called last, |
110 |
+ # otherwise Portage may wrongly assume sourcing failed |
111 |
+ return 0 |
112 |
+} |
113 |
+ |
114 |
# @FUNCTION: distutils_enable_tests |
115 |
# @USAGE: <test-runner> |
116 |
# @DESCRIPTION: |
117 |
-- |
118 |
2.24.0 |