[gentoo-dev] [PATCH 1/4] distutils-r1.eclass: Add distutils_enable_sphinx helper function

[gentoo-dev] [PATCH 1/4] distutils-r1.eclass: Add distutils_enable_sphinx helper function

[Michał Górny]

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 <mgorny@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

[gentoo-dev] [PATCH 2/4] dev-python/cssselect: Use distutils_enable_sphinx

[Michał Górny]

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 dev-python/cssselect/cssselect-1.0.3.ebuild | 26 ++-------------------
 1 file changed, 2 insertions(+), 24 deletions(-)

diff --git a/dev-python/cssselect/cssselect-1.0.3.ebuild b/dev-python/cssselect/cssselect-1.0.3.ebuild
index 80aef78e55b9..eb7e80a7db75 100644
--- a/dev-python/cssselect/cssselect-1.0.3.ebuild
+++ b/dev-python/cssselect/cssselect-1.0.3.ebuild
@@ -16,34 +16,12 @@ SRC_URI="https://github.com/scrapy/cssselect/archive/v${PV}.tar.gz -> ${P}.tar.g
 LICENSE="BSD"
 SLOT="0"
 KEYWORDS="~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~x86"
-IUSE="doc test"
+IUSE="test"
 RESTRICT="!test? ( test )"
 
 DEPEND="
 	dev-python/setuptools[${PYTHON_USEDEP}]
-	doc? ( $(python_gen_any_dep 'dev-python/sphinx[${PYTHON_USEDEP}]') )
 	test? ( dev-python/lxml[${PYTHON_USEDEP}] )"
 
+distutils_enable_sphinx docs
 distutils_enable_tests unittest
-
-python_check_deps() {
-	use doc || return 0
-	has_version "dev-python/sphinx[${PYTHON_USEDEP}]"
-}
-
-python_prepare_all() {
-	# prevent non essential d'load of files in doc build
-	sed -e 's:intersphinx_:#&:' -i docs/conf.py || die
-	distutils-r1_python_prepare_all
-}
-
-python_compile_all() {
-	if use doc ; then
-		esetup.py build_sphinx
-	fi
-}
-
-python_install_all() {
-	use doc && local HTML_DOCS=( docs/_build/html/. )
-	distutils-r1_python_install_all
-}
-- 
2.24.0

[gentoo-dev] [PATCH 3/4] dev-python/future: Use distutils_enable_sphinx

[Michał Górny]

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 dev-python/future/future-0.18.2.ebuild | 23 +++--------------------
 1 file changed, 3 insertions(+), 20 deletions(-)

diff --git a/dev-python/future/future-0.18.2.ebuild b/dev-python/future/future-0.18.2.ebuild
index d5b55ddea8d2..91b1a6a29af8 100644
--- a/dev-python/future/future-0.18.2.ebuild
+++ b/dev-python/future/future-0.18.2.ebuild
@@ -17,16 +17,12 @@ KEYWORDS="~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~mips ~ppc ~ppc64 ~s390 ~sparc ~
 IUSE="doc"
 
 distutils_enable_tests pytest
+distutils_enable_sphinx docs \
+	dev-python/sphinx-bootstrap-theme
 
 # TODO: make numpy unconditional when it supports py3.8
-BDEPEND="
+BDEPEND+="
 	dev-python/setuptools[${PYTHON_USEDEP}]
-	doc? (
-		$(python_gen_any_dep '
-			dev-python/sphinx[${PYTHON_USEDEP}]
-			dev-python/sphinx-bootstrap-theme[${PYTHON_USEDEP}]
-		')
-	)
 	test? (
 		$(python_gen_cond_dep 'dev-python/numpy[${PYTHON_USEDEP}]' \
 			python{2_7,3_{5,6,7}})
@@ -37,12 +33,6 @@ PATCHES=(
 	"${FILESDIR}"/${P}-tests.patch
 )
 
-python_check_deps() {
-	use doc || return 0
-	has_version "dev-python/sphinx[${PYTHON_USEDEP}]" &&
-		has_version "dev-python/sphinx-bootstrap-theme[${PYTHON_USEDEP}]"
-}
-
 python_prepare_all() {
 	sed -i "/'sphinx.ext.intersphinx'/d" docs/conf.py || die
 	# tests requiring network access
@@ -52,10 +42,3 @@ python_prepare_all() {
 
 	distutils-r1_python_prepare_all
 }
-
-python_compile_all() {
-	if use doc; then
-		sphinx-build docs/ docs/_build/html || die
-		HTML_DOCS=( docs/_build/html/. )
-	fi
-}
-- 
2.24.0

[gentoo-dev] [PATCH 4/4] dev-python/jinja: Use distutils_enable_sphinx

[Michał Górny]

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 dev-python/jinja/jinja-2.10.3-r1.ebuild | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)

diff --git a/dev-python/jinja/jinja-2.10.3-r1.ebuild b/dev-python/jinja/jinja-2.10.3-r1.ebuild
index 39131f10d5a9..f021773e3385 100644
--- a/dev-python/jinja/jinja-2.10.3-r1.ebuild
+++ b/dev-python/jinja/jinja-2.10.3-r1.ebuild
@@ -17,20 +17,18 @@ SRC_URI="https://github.com/pallets/jinja/archive/${PV}.tar.gz -> ${P}.tar.gz"
 LICENSE="BSD"
 SLOT="0"
 KEYWORDS="~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~x86 ~amd64-linux ~x86-linux ~x64-macos ~x86-macos ~sparc-solaris ~sparc64-solaris ~x64-solaris"
-IUSE="doc examples test"
+IUSE="examples test"
 RESTRICT="!test? ( test )"
 
 CDEPEND="dev-python/setuptools[${PYTHON_USEDEP}]
 	!dev-python/jinja:compat"
 RDEPEND="${CDEPEND}
 	dev-python/markupsafe[${PYTHON_USEDEP}]"
-BDEPEND="${CDEPEND}
-	doc? (
-		dev-python/sphinx
-		dev-python/sphinx-issues
-		dev-python/pallets-sphinx-themes
-	)"
+BDEPEND="${CDEPEND}"
 
+distutils_enable_sphinx docs \
+	dev-python/sphinx-issues \
+	dev-python/pallets-sphinx-themes
 distutils_enable_tests pytest
 
 # XXX: handle Babel better?
@@ -64,12 +62,7 @@ python_compile() {
 	wrap_opts distutils-r1_python_compile
 }
 
-python_compile_all() {
-	use doc && emake -C docs html
-}
-
 python_install_all() {
-	use doc && local HTML_DOCS=( docs/_build/html/. )
 	if use examples ; then
 		docinto examples
 		dodoc -r examples/.
-- 
2.24.0

Re: [gentoo-dev] [PATCH 1/4] distutils-r1.eclass: Add distutils_enable_sphinx helper function

[Patrick McLean]

Hi Michał,

Thanks for doing this work, it's always better to have standardized
ways of doing things.

On Wed, 20 Nov 2019 15:21:55 +0100
Michał Górny <mgorny@gentoo.org> wrote:

<snip>

> +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
> +		}

I think it would be better to put this code in sphinx_check_deps
(or some such) and define a python_check_deps that just calls
sphinx_check_deps. That would allow ebuilds that need to do more than
the sphinx stuff to not have to reimplement this.

> +	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

Since this is just searching for a fixed string maybe
"grep -F -q 'sphinx.ext.autodoc'" is a bit nicer.

> +				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/." )
> +	}

Same as above, I think it would be better to define this as
sphinx_compile, and define a python_compile_all that just calls it.
That way if an ebuild defines it's own python_compile_all it can call
sphinx_compile to get this functionality.

> +
> +	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:

Re: [gentoo-dev] [PATCH 1/4] distutils-r1.eclass: Add distutils_enable_sphinx helper function

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 3600 bytes --]

On Wed, 2019-11-20 at 10:23 -0800, Patrick McLean wrote:
> Hi Michał,
> 
> Thanks for doing this work, it's always better to have standardized
> ways of doing things.
> 
> On Wed, 20 Nov 2019 15:21:55 +0100
> Michał Górny <mgorny@gentoo.org> wrote:
> 
> <snip>
> 
> > +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
> > +		}
> 
> I think it would be better to put this code in sphinx_check_deps
> (or some such) and define a python_check_deps that just calls
> sphinx_check_deps. That would allow ebuilds that need to do more than
> the sphinx stuff to not have to reimplement this.

They would have to reimplement stuff anyway since it needs to be exactly
paired with python_gen_any_dep.

> 
> > +	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
> 
> Since this is just searching for a fixed string maybe
> "grep -F -q 'sphinx.ext.autodoc'" is a bit nicer.

Hmm, probably yes, indeed.

> 
> > +				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/." )
> > +	}
> 
> Same as above, I think it would be better to define this as
> sphinx_compile, and define a python_compile_all that just calls it.
> That way if an ebuild defines it's own python_compile_all it can call
> sphinx_compile to get this functionality.

I suppose it makes sense here.

> 
> > +
> > +	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:
> 
> 

-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]