summaryrefslogtreecommitdiff
path: root/eclass/docs.eclass
diff options
context:
space:
mode:
Diffstat (limited to 'eclass/docs.eclass')
-rw-r--r--eclass/docs.eclass81
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