[gentoo-dev] [PATCH v3 1/5] python-utils-r1.eclass: Introduce build_sphins() helper

[gentoo-dev] [PATCH v3 1/5] python-utils-r1.eclass: Introduce build_sphins() helper

[Michał Górny]

Introduce a helper to build HTML docs using Sphinx, providing for
Intersphinx cleanup and HTML_DOCS appending.

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 eclass/python-utils-r1.eclass | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

(changes in PATCH 2)

diff --git a/eclass/python-utils-r1.eclass b/eclass/python-utils-r1.eclass
index 647eb04344d2..f507b28ca90c 100644
--- a/eclass/python-utils-r1.eclass
+++ b/eclass/python-utils-r1.eclass
@@ -1344,6 +1344,31 @@ python_export_utf8_locale() {
 	return 0
 }
 
+# @FUNCTION: build_sphinx
+# @USAGE: <directory>
+# @DESCRIPTION:
+# Build HTML documentation using dev-python/sphinx in the specified
+# <directory>.  Takes care of disabling Intersphinx and appending
+# to HTML_DOCS.
+#
+# If <directory> is relative to the current directory, care needs
+# to be taken to run einstalldocs from the same directory
+# (usually ${S}).
+build_sphinx() {
+	debug-print-function ${FUNCNAME} "${@}"
+	[[ ${#} -eq 1 ]] || die "${FUNCNAME} takes 1 arg: <directory>"
+
+	local dir=${1}
+
+	sed -i -e 's:^intersphinx_mapping:disabled_&:' \
+		"${dir}"/conf.py || die
+	# not all packages include the Makefile in pypi tarball
+	sphinx-build -b html -d "${dir}"/_build/doctrees "${dir}" \
+		"${dir}"/_build/html || die
+
+	HTML_DOCS+=( "${dir}/_build/html/." )
+}
+
 # -- python.eclass functions --
 
 _python_check_dead_variables() {
-- 
2.24.0

[gentoo-dev] [PATCH v3 2/5] 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 | 96 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

Changed in v3:
- move the impl from python_compile_all to sphinx_compile_all, to make
  it possible to override it easily.

diff --git a/eclass/distutils-r1.eclass b/eclass/distutils-r1.eclass
index 63e77bf014c1..6e75a3a79914 100644
--- a/eclass/distutils-r1.eclass
+++ b/eclass/distutils-r1.eclass
@@ -232,6 +232,102 @@ 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.  If you need to extend
+# python_compile_all(), you can call the original implementation
+# as sphinx_compile_all.
+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
+
+	sphinx_compile_all() {
+		use doc || return
+
+		local confpy=${_DISTUTILS_SPHINX_SUBDIR}/conf.py
+		[[ -f ${confpy} ]] ||
+			die "${confpy} not found, distutils_enable_sphinx call wrong"
+
+		if [[ ${_DISTUTILS_SPHINX_PLUGINS[0]} == --no-autodoc ]]; then
+			if grep -F -q 'sphinx.ext.autodoc' "${confpy}"; then
+				die "distutils_enable_sphinx: --no-autodoc passed but sphinx.ext.autodoc found in ${confpy}"
+			fi
+		else
+			if ! grep -F -q 'sphinx.ext.autodoc' "${confpy}"; then
+				die "distutils_enable_sphinx: sphinx.ext.autodoc not found in ${confpy}, pass --no-autodoc"
+			fi
+		fi
+
+		build_sphinx "${_DISTUTILS_SPHINX_SUBDIR}"
+	}
+	python_compile_all() { sphinx_compile_all; }
+
+	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 v3 3/5] 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 v3 4/5] 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 v3 5/5] 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 v3 1/5] python-utils-r1.eclass: Introduce build_sphins() helper

[Kent Fredric]

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

On Fri, 22 Nov 2019 07:46:45 +0100
Michał Górny <mgorny@gentoo.org> wrote:

> Cc: python@gentoo.org,  Michał Górny <mgorny@gentoo.org>
> Subject: [gentoo-dev] [PATCH v3 1/5] python-utils-r1.eclass: Introduce build_sphins() helper
> Date: Fri, 22 Nov 2019 07:46:45 +0100
> Reply-to: gentoo-dev@lists.gentoo.org

You have a typo in the subject.

sphin[s]  instead of
sphin[x]

That's about the extent of my helpfulness, sorry :(

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [gentoo-dev] [PATCH v3 1/5] python-utils-r1.eclass: Introduce build_sphins() helper

[Michał Górny]

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

On Fri, 2019-11-22 at 22:43 +1300, Kent Fredric wrote:
> On Fri, 22 Nov 2019 07:46:45 +0100
> Michał Górny <mgorny@gentoo.org> wrote:
> 
> > Cc: python@gentoo.org,  Michał Górny <mgorny@gentoo.org>
> > Subject: [gentoo-dev] [PATCH v3 1/5] python-utils-r1.eclass: Introduce build_sphins() helper
> > Date: Fri, 22 Nov 2019 07:46:45 +0100
> > Reply-to: gentoo-dev@lists.gentoo.org
> 
> You have a typo in the subject.
> 
> sphin[s]  instead of
> sphin[x]
> 
> That's about the extent of my helpfulness, sorry :(

Fixed locally, thanks.

-- 
Best regards,
Michał Górny


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