Add a helper function to easily take care of the most common
dev-python/sphinx usage for HTML doc building.
Signed-off-by: Michał Górny <mgo...@gentoo.org>
---
eclass/distutils-r1.eclass | 98 ++++++++++++++++++++++++++++++++++++++
1 file changed, 98 insertions(+)
diff --git a/eclass/distutils-r1.eclass b/eclass/distutils-r1.eclass
index 63e77bf014c1..72fb664023fc 100644
--- a/eclass/distutils-r1.eclass
+++ b/eclass/distutils-r1.eclass
@@ -232,6 +232,104 @@ fi
# }
# @CODE
+# @FUNCTION: distutils_enable_sphinx
+# @USAGE: <subdir> [--no-autodoc | <plugin-pkgs>...]
+# @DESCRIPTION:
+# Set up IUSE, BDEPEND, python_check_deps() and python_compile_all() for
+# building HTML docs via dev-python/sphinx. python_compile_all() will
+# append to HTML_DOCS if docs are enabled.
+#
+# This helper is meant for the most common case, that is a single Sphinx
+# subdirectory with standard layout, building and installing HTML docs
+# behind USE=doc. It assumes it's the only consumer of the three
+# aforementioned functions. If you need to use a custom implemention,
+# you can't use it.
+#
+# If your package uses additional Sphinx plugins, they should be passed
+# (without PYTHON_USEDEP) as <plugin-pkgs>. The function will take care
+# of setting appropriate any-of dep and python_check_deps().
+#
+# If no plugin packages are specified, the eclass will still utilize
+# any-r1 API to support autodoc (documenting source code).
+# If the package uses neither autodoc nor additional plugins, you should
+# pass --no-autodoc to disable this API and simplify the resulting code.
+#
+# This function must be called in global scope. Take care not to
+# overwrite the variables set by it.
+distutils_enable_sphinx() {
+ debug-print-function ${FUNCNAME} "${@}"
+ [[ ${#} -ge 1 ]] || die "${FUNCNAME} takes at least one arg: <subdir>"
+
+ _DISTUTILS_SPHINX_SUBDIR=${1}
+ shift
+ _DISTUTILS_SPHINX_PLUGINS=( "${@}" )
+
+ local deps autodoc=1 d
+ for d; do
+ if [[ ${d} == --no-autodoc ]]; then
+ autodoc=
+ else
+ deps+="
+ ${d}[\${PYTHON_USEDEP}]"
+ fi
+ done
+
+ if [[ ! ${autodoc} && -n ${deps} ]]; then
+ die "${FUNCNAME}: do not pass --no-autodoc if external plugins
are used"
+ fi
+ if [[ ${autodoc} ]]; then
+ deps="$(python_gen_any_dep "
+ dev-python/sphinx[\${PYTHON_USEDEP}]
+ ${deps}")"
+
+ python_check_deps() {
+ use doc || return 0
+ local p
+ for p in "${_DISTUTILS_SPHINX_PLUGINS[@]}"; do
+ has_version "${p}[${PYTHON_USEDEP}]" || return 1
+ done
+ }
+ else
+ deps="dev-python/sphinx"
+ fi
+
+ python_compile_all() {
+ use doc || return
+
+ cd "${_DISTUTILS_SPHINX_SUBDIR}" || die
+ [[ -f conf.py ]] ||
+ die "conf.py not found, distutils_enable_sphinx call
wrong"
+
+ if [[ ${_DISTUTILS_SPHINX_PLUGINS[0]} == --no-autodoc ]]; then
+ if grep -q 'sphinx\.ext\.autodoc' "conf.py"; then
+ die "distutils_enable_sphinx: --no-autodoc
passed but sphinx.ext.autodoc found in conf.py"
+ fi
+ else
+ if ! grep -q 'sphinx\.ext\.autodoc' "conf.py"; then
+ die "distutils_enable_sphinx:
sphinx.ext.autodoc not found in conf.py, pass --no-autodoc"
+ fi
+ fi
+
+ # disable intersphinx (internet use)
+ sed -e 's:^intersphinx_mapping:disabled_&:' -i conf.py || die
+ # not all packages include the Makefile in pypi tarball
+ sphinx-build -b html -d _build/doctrees . _build/html || die
+
+ HTML_DOCS+=( "${_DISTUTILS_SPHINX_SUBDIR}/_build/html/." )
+ }
+
+ IUSE+=" doc"
+ if [[ ${EAPI} == [56] ]]; then
+ DEPEND+=" doc? ( ${deps} )"
+ else
+ BDEPEND+=" doc? ( ${deps} )"
+ fi
+
+ # we need to ensure successful return in case we're called last,
+ # otherwise Portage may wrongly assume sourcing failed
+ return 0
+}
+
# @FUNCTION: distutils_enable_tests
# @USAGE: <test-runner>
# @DESCRIPTION:
--
2.24.0
