Gentoo Archives: gentoo-dev

From: "Michał Górny" <mgorny@g.o>
To: gentoo-dev@l.g.o
Cc: python@g.o, "Michał Górny" <mgorny@g.o>
Subject: [gentoo-dev] [PATCH 1/4] distutils-r1.eclass: Add distutils_enable_sphinx helper function
Date: Wed, 20 Nov 2019 14:22:32
Message-Id: 20191120142158.157436-1-mgorny@gentoo.org
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

Replies