diff options
Diffstat (limited to 'eclass/docs.eclass')
| -rw-r--r-- | eclass/docs.eclass | 81 |
1 files changed, 63 insertions, 18 deletions
diff --git a/eclass/docs.eclass b/eclass/docs.eclass index 611485c227ff..5a63044a8646 100644 --- a/eclass/docs.eclass +++ b/eclass/docs.eclass @@ -1,4 +1,4 @@ -# Copyright 1999-2021 Gentoo Authors +# Copyright 1999-2022 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 # @ECLASS: docs.eclass @@ -143,6 +143,15 @@ esac # # Defaults to Doxyfile for doxygen +# @ECLASS_VARIABLE: DOCS_INITIALIZE_GIT +# @DEFAULT_UNSET +# @PRE_INHERIT +# @DESCRIPTION: +# Sometimes building the documentation will fail if this is not done +# inside a git repository. If this variable is set the compile functions +# will initialize a dummy git repository before compiling. A dependency +# on dev-vcs/git is automatically added. + if [[ ! ${_DOCS} ]]; then # For the python based DOCS_BUILDERS we need to inherit any python eclass @@ -164,6 +173,24 @@ case ${DOCS_BUILDER} in ;; esac +# @FUNCTION: initialize_git_repo +# @DESCRIPTION: +# Initializes a dummy git repository. This function is called by the +# documentation compile functions if DOCS_INITIALIZE_GIT is set. It can +# also be called manually. +initialize_git_repo() { + # Only initialize if we are not already in a git repository + local git_is_initialized="$(git rev-parse --is-inside-work-tree 2> /dev/null)" + if [[ ! "${git_is_initialized}" ]]; then + git init -q || die + git config --global user.email "larry@gentoo.org" || die + git config --global user.name "Larry the Cow" || die + git add . || die + git commit -qm "init" || die + git tag -a "${PV}" -m "${PN} version ${PV}" || die + fi +} + # @FUNCTION: python_append_deps # @INTERNAL # @DESCRIPTION: @@ -207,16 +234,17 @@ 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"} + + [[ ${DOCS_INITIALIZE_GIT} ]] && initialize_git_repo + local confpy=${DOCS_DIR}/conf.py [[ -f ${confpy} ]] || die "${FUNCNAME}: ${confpy} not found, DOCS_DIR=${DOCS_DIR} call wrong" @@ -236,6 +264,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 +297,17 @@ 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"} + + [[ ${DOCS_INITIALIZE_GIT} ]] && initialize_git_repo + local mkdocsyml=${DOCS_DIR}/mkdocs.yml [[ -f ${mkdocsyml} ]] || die "${FUNCNAME}: ${mkdocsyml} not found, DOCS_DIR=${DOCS_DIR} wrong" @@ -285,6 +320,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 +340,18 @@ 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"} + + [[ ${DOCS_INITIALIZE_GIT} ]] && initialize_git_repo local doxyfile=${DOCS_DIR}/${DOCS_CONFIG_NAME} [[ -f ${doxyfile} ]] || @@ -318,6 +363,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 +394,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 @@ -378,6 +421,8 @@ case ${DOCS_BUILDER} in ;; esac +[[ ${DOCS_INITIALIZE_GIT} ]] && DOCS_DEPEND+=" dev-vcs/git " + if [[ ${EAPI} != 6 ]]; then BDEPEND+=" doc? ( ${DOCS_DEPEND} )" else |