python-single-r1 does not have the python_gen_any_dep function (unlike
python-r1). This makes dependency resolution fail if an ebuild tries to
enable doc building (using docs.eclass or distutils_enable_sphinx) while
DISTUTILS_SINGLE_IMPL is set and/or python-single-r1 is inherited. See
also bug: https://bugs.gentoo.org/704520 . The python_gen_cond_dep
function should be used instead in these cases.
Therefore, I propose the following small changes to docs.eclass and
distutils-r1.eclass (in the next email), PR is open here:
https://github.com/gentoo/gentoo/pull/19078
Best regards,
Andrew
From 7b3a170cfc85120f512bd8da5201ed1f59beeabe Mon Sep 17 00:00:00 2001
From: Andrew Ammerlaan <andrewammerl...@riseup.net>
Date: Sat, 16 Jan 2021 14:28:53 +0100
Subject: [PATCH] eclass/docs.eclass: make compatible with python-single-r1
python-single-r1 does not have the pyhton_gen_any-dep
function, use the pyhton_gen_cond_dep instead
also a much needed update to the documentation
of this eclass. Fixed typos, and added proper
examples.
Signed-off-by: Andrew Ammerlaan <andrewammerl...@riseup.net>
---
eclass/docs.eclass | 173 +++++++++++++++++++++++++++++++++------------
1 file changed, 128 insertions(+), 45 deletions(-)
diff --git a/eclass/docs.eclass b/eclass/docs.eclass
index adacae4abda64..ca198faf31470 100644
--- a/eclass/docs.eclass
+++ b/eclass/docs.eclass
@@ -10,20 +10,52 @@
# @SUPPORTED_EAPIS: 6 7
# @BLURB: A simple eclass to build documentation.
# @DESCRIPTION:
-# A simple eclass providing functions to build documentation.
+# A simple eclass providing basic functions and variables to build
+# documentation.
#
-# Please note that docs sets RDEPEND and DEPEND unconditionally
-# for you.
+# Please note that this eclass appends to RDEPEND and DEPEND
+# unconditionally for you.
#
# This eclass also appends "doc" to IUSE, and sets HTML_DOCS
-# to the location of the compiled documentation
+# to the location of the compiled documentation automatically,
+# 'einstalldocs' will then automatically install the documentation
+# to the correct directory.
#
# The aim of this eclass is to make it easy to add additional
-# doc builders. To do this, add a <DOCS_BUILDER>-deps and
-# <DOCS_BUILDER>-build function for your doc builder.
+# doc builders. To do this, add a <DOCS_BUILDER>_deps and
+# <DOCS_BUILDER>_compile function for your doc builder.
# For python based doc builders you can use the
# python_append_deps function to append [${PYTHON_USEDEP}]
# automatically to additional dependencies.
+#
+# Example use doxygen:
+# @CODE
+# DOCS_BUILDER="doxygen"
+# DOCS_DEPEND="media-gfx/imagemagick"
+# DOCS_DIR="docs"
+#
+# inherit docs
+#
+# ...
+#
+# src_compile() {
+# default
+# docs_compile
+# }
+# @CODE
+#
+# Example use mkdocs with distutils-r1:
+# @CODE
+# DOCS_BUILDER="mkdocs"
+# DOCS_DEPEND="dev-python/mkdocs-material"
+# DOCS_DIR="doc"
+#
+# PYTHON_COMPAT=( python3_{7,8,9} )
+#
+# inherit distutils-r1 docs
+#
+# ...
+# @CODE
case "${EAPI:-0}" in
0|1|2|3|4|5)
@@ -50,41 +82,54 @@ esac
# Path containing the doc builder config file(s).
#
# For sphinx this is the location of "conf.py"
-# For mkdocs this is the location of "mkdocs.yml"
#
+# For mkdocs this is the location of "mkdocs.yml"
# Note that mkdocs.yml often does not reside
# in the same directory as the actual doc files
#
+# For doxygen the default name is Doxyfile, but
+# package may use a non-standard name. If this
+# is the case one should set DOCS_CONFIG_NAME to
+# the correct name
+#
# Defaults to ${S}
# @ECLASS-VARIABLE: DOCS_DEPEND
# @DEFAULT_UNSET
# @PRE_INHERIT
# @DESCRIPTION:
-# Sets additional dependencies to build docs.
+# Sets additional dependencies required to build the
+# documentation.
# For sphinx and mkdocs these dependencies should
-# be specified without [${PYTHON_USEDEP}], this
+# be specified *without* [${PYTHON_USEDEP}], this
# is added by the eclass. E.g. to depend on mkdocs-material:
#
+# @CODE
# DOCS_DEPEND="dev-python/mkdocs-material"
+# @CODE
#
-# This eclass appends to this variable, so you can
-# call it later in your ebuild again if necessary.
+# This eclass appends to this variable, this makes it
+# possible to call it later in your ebuild again if
+# necessary.
# @ECLASS-VARIABLE: DOCS_AUTODOC
# @PRE_INHERIT
# @DESCRIPTION:
# Sets whether to use sphinx.ext.autodoc/mkautodoc
-# Defaults to 1 (True) for sphinx, and 0 (False) for mkdocs
+# Defaults to 1 (True) for sphinx, and 0 (False) for mkdocs.
+# Not relevant for doxygen.
# @ECLASS-VARIABLE: DOCS_OUTDIR
# @DESCRIPTION:
-# Sets where the compiled files will be put.
-# There's no real reason to change this, but this
-# variable is useful if you want to overwrite the HTML_DOCS
-# added by this eclass. E.g.:
+# Sets the directory where the documentation should
+# be built into. There is no real reason to change this.
+# However, this variable is useful if the package should
+# also install other HTML files.
#
+# Example use:
+# @CODE
# HTML_DOCS=( "${yourdocs}" "${DOCS_OUTDIR}/." )
+# @CODE
#
# Defaults to ${S}/_build/html
@@ -93,18 +138,19 @@ esac
# Name of the doc builder config file.
#
# Only relevant for doxygen, as it allows
-# config files with non-standard names
+# config files with non-standard names.
+# Does not do anything for mkdocs or sphinx.
#
# Defaults to Doxyfile for doxygen
if [[ ! ${_DOCS} ]]; then
-# For the python based DOCS_BUILDERS we need to inherit python-any-r1
+# For the python based DOCS_BUILDERS we need to inherit any python eclass
case ${DOCS_BUILDER} in
"sphinx"|"mkdocs")
# We need the python_gen_any_dep function
- if [[ ! ${_PYTHON_R1} && ! ${_PYTHON_ANY_R1} ]]; then
- die "python-r1 or python-any-r1 needs to be inherited as
well to use python based documentation builders"
+ if [[ ! ${_PYTHON_R1} && ! ${_PYTHON_ANY_R1} && !
${_PYTHON_SINGLE_R1} ]]; then
+ die "distutils-r1, python-r1, python-single-r1 or
python-any-r1 needs to be inherited to use python based documentation builders"
fi
;;
"doxygen")
@@ -119,6 +165,7 @@ case ${DOCS_BUILDER} in
esac
# @FUNCTION: python_append_dep
+# @INTERNAL
# @DESCRIPTION:
# Appends [\${PYTHON_USEDEP}] to all dependencies
# for python based DOCS_BUILDERs such as mkdocs or
@@ -135,6 +182,7 @@ python_append_deps() {
}
# @FUNCTION: sphinx_deps
+# @INTERNAL
# @DESCRIPTION:
# Sets dependencies for sphinx
sphinx_deps() {
@@ -146,24 +194,36 @@ sphinx_deps() {
if [[ -n "${DOCS_DEPEND}" ]]; then
die "${FUNCNAME}: do not set DOCS_AUTODOC to 0 if external
plugins are used"
else
- DOCS_DEPEND="$(python_gen_any_dep "
- dev-python/sphinx[\${PYTHON_USEDEP}]")"
+ if [[ ${_PYTHON_SINGLE_R1} ]]; then
+ DOCS_DEPEND="$(python_gen_cond_dep "
+ dev-python/sphinx[\${PYTHON_USEDEP}]")"
+ else
+ DOCS_DEPEND="$(python_gen_any_dep "
+ dev-python/sphinx[\${PYTHON_USEDEP}]")"
+ fi
fi
elif [[ ${DOCS_AUTODOC} == 1 ]]; then
- DOCS_DEPEND="$(python_gen_any_dep "
- dev-python/sphinx[\${PYTHON_USEDEP}]
- ${DOCS_DEPEND}")"
+ if [[ ${_PYTHON_SINGLE_R1} ]]; then
+ DOCS_DEPEND="$(python_gen_cond_dep "
+ dev-python/sphinx[\${PYTHON_USEDEP}]
+ ${DOCS_DEPEND}")"
+ else
+ DOCS_DEPEND="$(python_gen_any_dep "
+ dev-python/sphinx[\${PYTHON_USEDEP}]
+ ${DOCS_DEPEND}")"
+ fi
else
die "${FUNCNAME}: DOCS_AUTODOC should be set to 0 or 1"
fi
}
# @FUNCTION: sphinx_compile
+# @INTERNAL
# @DESCRIPTION:
# Calls sphinx to build docs.
#
-# If you overwrite src_compile or python_compile_all
-# do not call this function, call docs_compile instead
+# If you overwrite python_compile_all do not call
+# this function, call docs_compile instead
sphinx_compile() {
debug-print-function ${FUNCNAME}
use doc || return
@@ -190,6 +250,7 @@ sphinx_compile() {
}
# @FUNCTION: mkdocs_deps
+# @INTERNAL
# @DESCRIPTION:
# Sets dependencies for mkdocs
mkdocs_deps() {
@@ -198,25 +259,39 @@ mkdocs_deps() {
: ${DOCS_AUTODOC:=0}
if [[ ${DOCS_AUTODOC} == 1 ]]; then
- DOCS_DEPEND="$(python_gen_any_dep "
- dev-python/mkdocs[\${PYTHON_USEDEP}]
- dev-python/mkautodoc[\${PYTHON_USEDEP}]
- ${DOCS_DEPEND}")"
- elif [[ ${DOCS_AUTODOC} == 0 ]]; then
- DOCS_DEPEND="$(python_gen_any_dep "
- dev-python/mkdocs[\${PYTHON_USEDEP}]
+ if [[ ${_PYTHON_SINGLE_R1} ]]; then
+ DOCS_DEPEND="$(python_gen_cond_dep "
+ dev-python/mkdocs[\${PYTHON_USEDEP}]
+ dev-python/mkautodoc[\${PYTHON_USEDEP}]
+ ${DOCS_DEPEND}")"
+ else
+ DOCS_DEPEND="$(python_gen_any_dep "
+ dev-python/mkdocs[\${PYTHON_USEDEP}]
+ dev-python/mkautodoc[\${PYTHON_USEDEP}]
${DOCS_DEPEND}")"
+ fi
+ elif [[ ${DOCS_AUTODOC} == 0 ]]; then
+ if [[ ${_PYTHON_SINGLE_R1} ]]; then
+ DOCS_DEPEND="$(python_gen_cond_dep "
+ dev-python/mkdocs[\${PYTHON_USEDEP}]
+ ${DOCS_DEPEND}")"
+ else
+ DOCS_DEPEND="$(python_gen_any_dep "
+ dev-python/mkdocs[\${PYTHON_USEDEP}]
+ ${DOCS_DEPEND}")"
+ fi
else
die "${FUNCNAME}: DOCS_AUTODOC should be set to 0 or 1"
fi
}
# @FUNCTION: mkdocs_compile
+# @INTERNAL
# @DESCRIPTION:
# Calls mkdocs to build docs.
#
-# If you overwrite src_compile or python_compile_all
-# do not call this function, call docs_compile instead
+# If you overwrite python_compile_all do not call
+# this function, call docs_compile instead
mkdocs_compile() {
debug-print-function ${FUNCNAME}
use doc || return
@@ -236,6 +311,7 @@ mkdocs_compile() {
}
# @FUNCTION: doxygen_deps
+# @INTERNAL
# @DESCRIPTION:
# Sets dependencies for doxygen
doxygen_deps() {
@@ -246,11 +322,9 @@ doxygen_deps() {
}
# @FUNCTION: doxygen_compile
+# @INTERNAL
# @DESCRIPTION:
# Calls doxygen to build docs.
-#
-# If you overwrite src_compile or python_compile_all
-# do not call this function, call docs_compile instead
doxygen_compile() {
debug-print-function ${FUNCNAME}
use doc || return
@@ -273,12 +347,21 @@ doxygen_compile() {
# @DESCRIPTION:
# Calls DOCS_BUILDER and sets HTML_DOCS
#
-# This function must be called in global scope. Take care not to
-# overwrite the variables set by it. Has support for distutils-r1
-# eclass, but only if this eclass is inherited *after*
-# distutils-r1. If you need to extend src_compile() or
-# python_compile_all(), you can call the original implementation
-# as docs_compile.
+# This function must be called in src_compile. Take care not to
+# overwrite the variables set by it. If distutils-r1 is inherited
+# *before* this eclass, than docs_compile will be automatically
+# added to python_compile_all() and there is no need to call
+# it manually. Note that this function checks if USE="doc" is
+# enabled, and if not automatically exits. Therefore, there is
+# no need to wrap this function in a if statement.
+#
+# Example use:
+# @CODE
+# src_compile() {
+# default
+# docs_compile
+# }
+# @CODE
docs_compile() {
debug-print-function ${FUNCNAME}
use doc || return
