Gentoo Archives: gentoo-dev

From: Andrew Ammerlaan <andrewammerlaan@g.o>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] [PATCH 1/2] docs.eclass: allow multiple documentation builders
Date: Thu, 10 Nov 2022 11:29:27
Message-Id: 32ed3f0d-e18d-ce92-9dc4-5e03a0ad07e4@gentoo.org
1 diff --git a/eclass/docs.eclass b/eclass/docs.eclass
2 index 611485c227f..f7a82939a53 100644
3 --- a/eclass/docs.eclass
4 +++ b/eclass/docs.eclass
5 @@ -207,16 +207,15 @@ sphinx_deps() {
6 }
7
8 # @FUNCTION: sphinx_compile
9 -# @INTERNAL
10 # @DESCRIPTION:
11 # Calls sphinx to build docs.
12 -#
13 -# If you overwrite python_compile_all do not call
14 -# this function, call docs_compile instead
15 sphinx_compile() {
16 debug-print-function ${FUNCNAME}
17 use doc || return
18
19 + : ${DOCS_DIR:="${S}"}
20 + : ${DOCS_OUTDIR:="${S}/_build/html/sphinx"}
21 +
22 local confpy=${DOCS_DIR}/conf.py
23 [[ -f ${confpy} ]] ||
24 die "${FUNCNAME}: ${confpy} not found, DOCS_DIR=${DOCS_DIR} call wrong"
25 @@ -236,6 +235,12 @@ sphinx_compile() {
26 # not all packages include the Makefile in pypi tarball
27 sphinx-build -b html -d "${DOCS_OUTDIR}"/_build/doctrees "${DOCS_DIR}" \
28 "${DOCS_OUTDIR}" || die "${FUNCNAME}: sphinx-build failed"
29 +
30 + HTML_DOCS+=( "${DOCS_OUTDIR}" )
31 +
32 + # We don't need these any more, unset them in case we want to call a
33 + # second documentation builder.
34 + unset DOCS_DIR DOCS_OUTDIR
35 }
36
37 # @FUNCTION: mkdocs_deps
38 @@ -263,16 +268,15 @@ mkdocs_deps() {
39 }
40
41 # @FUNCTION: mkdocs_compile
42 -# @INTERNAL
43 # @DESCRIPTION:
44 # Calls mkdocs to build docs.
45 -#
46 -# If you overwrite python_compile_all do not call
47 -# this function, call docs_compile instead
48 mkdocs_compile() {
49 debug-print-function ${FUNCNAME}
50 use doc || return
51
52 + : ${DOCS_DIR:="${S}"}
53 + : ${DOCS_OUTDIR:="${S}/_build/html/mkdocs"}
54 +
55 local mkdocsyml=${DOCS_DIR}/mkdocs.yml
56 [[ -f ${mkdocsyml} ]] ||
57 die "${FUNCNAME}: ${mkdocsyml} not found, DOCS_DIR=${DOCS_DIR} wrong"
58 @@ -285,6 +289,12 @@ mkdocs_compile() {
59 # mkdocs currently has no option to disable this
60 # and portage complains: "Colliding files found by ecompress"
61 rm "${DOCS_OUTDIR}"/*.gz || die
62 +
63 + HTML_DOCS+=( "${DOCS_OUTDIR}" )
64 +
65 + # We don't need these any more, unset them in case we want to call a
66 + # second documentation builder.
67 + unset DOCS_DIR DOCS_OUTDIR
68 }
69
70 # @FUNCTION: doxygen_deps
71 @@ -299,14 +309,16 @@ doxygen_deps() {
72 }
73
74 # @FUNCTION: doxygen_compile
75 -# @INTERNAL
76 # @DESCRIPTION:
77 # Calls doxygen to build docs.
78 doxygen_compile() {
79 debug-print-function ${FUNCNAME}
80 use doc || return
81
82 + # This is the default name of the config file, upstream can change it.
83 : ${DOCS_CONFIG_NAME:="Doxyfile"}
84 + : ${DOCS_DIR:="${S}"}
85 + : ${DOCS_OUTDIR:="${S}/_build/html/doxygen"}
86
87 local doxyfile=${DOCS_DIR}/${DOCS_CONFIG_NAME}
88 [[ -f ${doxyfile} ]] ||
89 @@ -318,6 +330,12 @@ doxygen_compile() {
90 pushd "${DOCS_DIR}" || die
91 (cat "${DOCS_CONFIG_NAME}" ; echo "HTML_OUTPUT=${DOCS_OUTDIR}") |
92 doxygen - || die "${FUNCNAME}: doxygen failed"
93 popd || die
94 +
95 + HTML_DOCS+=( "${DOCS_OUTDIR}" )
96 +
97 + # We don't need these any more, unset them in case we want to call a
98 + # second documentation builder.
99 + unset DOCS_DIR DOCS_OUTDIR DOCS_CONFIG_NAME
100 }
101
102 # @FUNCTION: docs_compile
103 @@ -343,16 +361,8 @@ docs_compile() {
104 debug-print-function ${FUNCNAME}
105 use doc || return
106
107 - # Set a sensible default as DOCS_DIR
108 - : ${DOCS_DIR:="${S}"}
109 -
110 - # Where to put the compiled files?
111 - : ${DOCS_OUTDIR:="${S}/_build/html"}
112 -
113 ${DOCS_BUILDER}_compile
114
115 - HTML_DOCS+=( "${DOCS_OUTDIR}/." )
116 -
117 # we need to ensure successful return in case we're called last,
118 # otherwise Portage may wrongly assume sourcing failed
119 return 0
120
121
122 diff --git a/net-libs/xrootd/xrootd-5.5.0.ebuild
123 b/net-libs/xrootd/xrootd-5.5.0.ebuild
124 index 53f8a65ef85..3acd41d1cb2 100644
125 --- a/net-libs/xrootd/xrootd-5.5.0.ebuild
126 +++ b/net-libs/xrootd/xrootd-5.5.0.ebuild
127 @@ -88,12 +91,8 @@ src_configure() {
128
129 src_compile() {
130 cmake_src_compile
131 - docs_compile
132 -
133 - # secondary documentation for python bindings
134 - if use python && use doc; then
135 - emake -C bindings/python/docs html
136 - fi
137 + doxygen_compile
138 + use python && DOCS_DIR="${S}/bindings/python/docs/source" sphinx_compile
139 }
140
141 src_install() {
142 @@ -121,11 +120,6 @@ src_install() {
143 if use python; then
144 python_optimize "${D}/$(python_get_sitedir)"
145
146 - if use doc; then
147 - docinto python
148 - docompress -x "/usr/share/doc/${PF}/python/html"
149 - dodoc -r bindings/python/docs/build/html
150 - fi
151 if use examples; then
152 docinto python
153 dodoc -r bindings/python/examples

Replies