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