• Re: [gentoo-dev] [PATCH 1/2] docs.eclass: allow multiple documentation

    From Anna@21:1/5 to Andrew Ammerlaan on Thu Nov 10 12:40:01 2022
    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


    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Andrew Ammerlaan@21:1/5 to Anna on Thu Nov 10 14:20:01 2022
    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.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)