* [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
* Re: [gentoo-dev] [PATCH 1/2] docs.eclass: allow multiple documentation builders
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
0 siblings, 1 reply; 3+ messages in thread
From: Anna @ 2022-11-10 11:38 UTC (permalink / raw
To: gentoo-dev
On 2022-11-10 12:29, Andrew Ammerlaan wrote:
> 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"}
> +
Could it be local?
> 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"}
> +
Ditto.
> 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"}
Ditto.
> 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 [flat|nested] 3+ messages in thread
* Re: [gentoo-dev] [PATCH 1/2] docs.eclass: allow multiple documentation builders
2022-11-10 11:38 ` Anna
@ 2022-11-10 13:16 ` Andrew Ammerlaan
0 siblings, 0 replies; 3+ messages in thread
From: Andrew Ammerlaan @ 2022-11-10 13:16 UTC (permalink / raw
To: gentoo-dev
On 10/11/2022 12:38, Anna wrote:
> On 2022-11-10 12:29, Andrew Ammerlaan wrote:
>> 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"}
>> +
>
> Could it be local?
I guess, but to me that feels a bit weird and confusing because this
variable can also be set globally in the ebuild.
^ permalink raw reply [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