public inbox for gentoo-dev@lists.gentoo.org
 help / color / mirror / Atom feed
* [gentoo-dev] [PATCH 1/2] docs.eclass: allow multiple documentation builders
@ 2022-11-10 11:29 Andrew Ammerlaan
  2022-11-10 11:38 ` Anna
  0 siblings, 1 reply; 3+ messages in thread
From: Andrew Ammerlaan @ 2022-11-10 11:29 UTC (permalink / raw
  To: gentoo-dev

diff --git a/eclass/docs.eclass b/eclass/docs.eclass
index 611485c227f..f7a82939a53 100644
--- a/eclass/docs.eclass
+++ b/eclass/docs.eclass
@@ -207,16 +207,15 @@ sphinx_deps() {
  }

  # @FUNCTION: sphinx_compile
-# @INTERNAL
  # @DESCRIPTION:
  # Calls sphinx to build docs.
-#
-# If you overwrite python_compile_all do not call
-# this function, call docs_compile instead
  sphinx_compile() {
  	debug-print-function ${FUNCNAME}
  	use doc || return

+	: ${DOCS_DIR:="${S}"}
+	: ${DOCS_OUTDIR:="${S}/_build/html/sphinx"}
+
  	local confpy=${DOCS_DIR}/conf.py
  	[[ -f ${confpy} ]] ||
  		die "${FUNCNAME}: ${confpy} not found, DOCS_DIR=${DOCS_DIR} call wrong"
@@ -236,6 +235,12 @@ sphinx_compile() {
  	# not all packages include the Makefile in pypi tarball
  	sphinx-build -b html -d "${DOCS_OUTDIR}"/_build/doctrees "${DOCS_DIR}" \
  	"${DOCS_OUTDIR}" || die "${FUNCNAME}: sphinx-build failed"
+
+	HTML_DOCS+=( "${DOCS_OUTDIR}" )
+
+	# We don't need these any more, unset them in case we want to call a
+	# second documentation builder.
+	unset DOCS_DIR DOCS_OUTDIR
  }

  # @FUNCTION: mkdocs_deps
@@ -263,16 +268,15 @@ mkdocs_deps() {
  }

  # @FUNCTION: mkdocs_compile
-# @INTERNAL
  # @DESCRIPTION:
  # Calls mkdocs to build docs.
-#
-# If you overwrite python_compile_all do not call
-# this function, call docs_compile instead
  mkdocs_compile() {
  	debug-print-function ${FUNCNAME}
  	use doc || return

+	: ${DOCS_DIR:="${S}"}
+	: ${DOCS_OUTDIR:="${S}/_build/html/mkdocs"}
+
  	local mkdocsyml=${DOCS_DIR}/mkdocs.yml
  	[[ -f ${mkdocsyml} ]] ||
  		die "${FUNCNAME}: ${mkdocsyml} not found, DOCS_DIR=${DOCS_DIR} wrong"
@@ -285,6 +289,12 @@ mkdocs_compile() {
  	# mkdocs currently has no option to disable this
  	# and portage complains: "Colliding files found by ecompress"
  	rm "${DOCS_OUTDIR}"/*.gz || die
+
+	HTML_DOCS+=( "${DOCS_OUTDIR}" )
+
+	# We don't need these any more, unset them in case we want to call a
+	# second documentation builder.
+	unset DOCS_DIR DOCS_OUTDIR
  }

  # @FUNCTION: doxygen_deps
@@ -299,14 +309,16 @@ doxygen_deps() {
  }

  # @FUNCTION: doxygen_compile
-# @INTERNAL
  # @DESCRIPTION:
  # Calls doxygen to build docs.
  doxygen_compile() {
  	debug-print-function ${FUNCNAME}
  	use doc || return

+	# This is the default name of the config file, upstream can change it.
  	: ${DOCS_CONFIG_NAME:="Doxyfile"}
+	: ${DOCS_DIR:="${S}"}
+	: ${DOCS_OUTDIR:="${S}/_build/html/doxygen"}

  	local doxyfile=${DOCS_DIR}/${DOCS_CONFIG_NAME}
  	[[ -f ${doxyfile} ]] ||
@@ -318,6 +330,12 @@ doxygen_compile() {
  	pushd "${DOCS_DIR}" || die
  	(cat "${DOCS_CONFIG_NAME}" ; echo "HTML_OUTPUT=${DOCS_OUTDIR}") | 
doxygen - || die "${FUNCNAME}: doxygen failed"
  	popd || die
+
+	HTML_DOCS+=( "${DOCS_OUTDIR}" )
+
+	# We don't need these any more, unset them in case we want to call a
+	# second documentation builder.
+	unset DOCS_DIR DOCS_OUTDIR DOCS_CONFIG_NAME
  }

  # @FUNCTION: docs_compile
@@ -343,16 +361,8 @@ docs_compile() {
  	debug-print-function ${FUNCNAME}
  	use doc || return

-	# Set a sensible default as DOCS_DIR
-	: ${DOCS_DIR:="${S}"}
-
-	# Where to put the compiled files?
-	: ${DOCS_OUTDIR:="${S}/_build/html"}
-
  	${DOCS_BUILDER}_compile

-	HTML_DOCS+=( "${DOCS_OUTDIR}/." )
-
  	# we need to ensure successful return in case we're called last,
  	# otherwise Portage may wrongly assume sourcing failed
  	return 0


diff --git a/net-libs/xrootd/xrootd-5.5.0.ebuild 
b/net-libs/xrootd/xrootd-5.5.0.ebuild
index 53f8a65ef85..3acd41d1cb2 100644
--- a/net-libs/xrootd/xrootd-5.5.0.ebuild
+++ b/net-libs/xrootd/xrootd-5.5.0.ebuild
@@ -88,12 +91,8 @@ src_configure() {

  src_compile() {
  	cmake_src_compile
-	docs_compile
-
-	# secondary documentation for python bindings
-	if use python && use doc; then
-		emake -C bindings/python/docs html
-	fi
+	doxygen_compile
+	use python && DOCS_DIR="${S}/bindings/python/docs/source" sphinx_compile
  }

  src_install() {
@@ -121,11 +120,6 @@ src_install() {
  	if use python; then
  		python_optimize "${D}/$(python_get_sitedir)"

-		if use doc; then
-			docinto python
-			docompress -x "/usr/share/doc/${PF}/python/html"
-			dodoc -r bindings/python/docs/build/html
-		fi
  		if use examples; then
  			docinto python
  			dodoc -r bindings/python/examples


^ permalink raw reply related	[flat|nested] 3+ messages in thread
end of thread, other threads:[~2022-11-10 13:16 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-11-10 11:29 [gentoo-dev] [PATCH 1/2] docs.eclass: allow multiple documentation builders Andrew Ammerlaan
2022-11-10 11:38 ` Anna
2022-11-10 13:16   ` Andrew Ammerlaan

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox