[PATCH 0/5] Fix and improve API page generation
This series cleans up some cruft unused for very long time, fixes the reference page for LXC API: Broken (until this patchset is merged): https://www.libvirt.org/html/libvirt-libvirt-lxc.html Fixed: https://pipo.sk.gitlab.io/-/libvirt/-/jobs/3268983196/artifacts/website/html... Removes pointless copy of the LGPL license at the top of the API refernece files such as: https://www.libvirt.org/html/libvirt-libvirt-qemu.html and removes the pointless specific index files such as: https://www.libvirt.org/html/index-qemu.html Peter Krempa (5): docs: xsl: newapi: Remove unused 'navbar' template docs: xsl: Don't format empty sections in API manual apibuild: Don't include the Copyright in the <description> of a module docs: Link directly to admin|qemu|lxc API reference pages docs: xsl: Don't generate pointless index pages for qemu/admin/lxc API docs/docs.rst | 6 +-- docs/html/home.png | Bin 654 -> 0 bytes docs/html/left.png | Bin 459 -> 0 bytes docs/html/meson.build | 16 +------ docs/html/right.png | Bin 472 -> 0 bytes docs/html/up.png | Bin 406 -> 0 bytes docs/newapi.xsl | 98 ++++++++++++++++++------------------------ scripts/apibuild.py | 8 ++++ 8 files changed, 55 insertions(+), 73 deletions(-) delete mode 100644 docs/html/home.png delete mode 100644 docs/html/left.png delete mode 100644 docs/html/right.png delete mode 100644 docs/html/up.png -- 2.37.3
The template is unused since commit 9092c3d491047539e376a496d1520249 Remove also the up|right|left|home.png files which were only used by code generated by the unused template. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/html/home.png | Bin 654 -> 0 bytes docs/html/left.png | Bin 459 -> 0 bytes docs/html/meson.build | 13 ------------- docs/html/right.png | Bin 472 -> 0 bytes docs/html/up.png | Bin 406 -> 0 bytes docs/newapi.xsl | 22 ---------------------- 6 files changed, 35 deletions(-) delete mode 100644 docs/html/home.png delete mode 100644 docs/html/left.png delete mode 100644 docs/html/right.png delete mode 100644 docs/html/up.png diff --git a/docs/html/home.png b/docs/html/home.png deleted file mode 100644 index 17003611d9df2b066afc682cbde962f3a575002d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 654 zcmV;90&)F`P)<h;3K|Lk000e1NJLTq000;O000;W1^@s6;CDUv00006VoOIv0RI60 z0RN!9r;`8x010qNS#tmY3labT3lag+-G2N4000McNliru(g+^~F$eY9OLhPN0vkz0 zK~#90)s?Yp6LB2HKi_gghu`3E!wDUJLxc_;Zg9MzLqS1G3ob$}Tqj3|4qZCjpp$=s zgG0v(EhvaMwBV2ofgaR=5Fv$T2t=@ufB}W)(vxd!Vp7||2XA@&c<=k}%kOt^!>~yY zO1cF+0vxb!W?!x?K+*#62Jq)nA4q`)5S6sgX4ao{=)(Mgq+YMr)7sjak|a^9)zS!j zlk{-n29mabXYF=7SYBQx&vO8xC}MYams+hxqtO7sImhPaCf@rq;I^3!#u*2aUP)55 zT2&N90xmEJ0s&fGT~(T<3d2xYmK9C>IP*x-M@ib*+0pFm>>uW37N2Wzaq-fCnIZE9 zpb8}0+uN+KuQM2oZVHfP8U6kQdo3?>Wo2dT)WeM9So8Dq<pxiO&9@}|I6Xa89LH0c zm+8IN(a}*6@={WOq$lH+IW3)Y+S}VJLS7*0L$}+NbMBwb%RFz=41hD|97{_}bUGbs zwHlR5g(OM-zPJ+dJSWd{;yA{8kM|y+gQUBXdXm&?wFD?l(@{5dB(f|Mpo4>hLi#T0 z-i(>mfjhvbsYV`;4sgfJ-p>G-SqJ!fjR6BQYs1h*y9xaN0l{VB;o%`08yiy@)$8@~ z2PD1gcDuiy;j1tR0v#V8OH%W)25-YKyx(j#IXO9*YWf0mb8}QG6@b@;cHxh9{t7+@ o!Yd`f8L$sLH?yBt^q3C6015TtIu@BS5dZ)H07*qoM6N<$f*igdr~m)} diff --git a/docs/html/left.png b/docs/html/left.png deleted file mode 100644 index 2d05b3d5b4aeec9384bbfe404bfc4ed0897051c4..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 459 zcmV;+0W|)JP)<h;3K|Lk000e1NJLTq000;O000;W1^@s6;CDUv00006VoOIv0RI60 z0RN!9r;`8x010qNS#tmY3labT3lag+-G2N4000McNliru(g+^~F($dQTPOek0a!^y zK~#90wUr@H!%!GS@7pR7h>40xL?wO*>WZ(J#ML5j2<9jD6A%Q&kC<R{2;7#CrE*JV zmb8MT;vi_30c~lQ$4Q=gefQk2N&BRh04{La_FR)-2YBR*42W!pKLc#HTe2(zNUVpi z*K0h_BaUML{v}+J9YIxiTY*!vH<lD`HXHfAujO*N-{|#vMTv)!b03nPj4`vi_LH*a z#cDtXoR>}jOeEc;X{s;`zcnxLeZR6?6h#^ihmNF6NpGdilO$m<82oD9WQ|6nVv1`? z>KufRi{?QPXg;4;wroQu4?mN1Ydd@|kaQ|ZyWLK!)yi7<USN!Ql{D-3`<hOta$VQ1 zAm>Wb%=0{}lD)tfliHAUyWRQ+fD_;aV6j->y6!O_8bENg<bb$jy#x1uj#?)vX!zFJ zORNd1Bvu7KCB<EUtt+!kl5=NOkV_okBL8<a;uAAZ0JjyD-0}bb002ovPDHLkV1kj6 B!Ug~U diff --git a/docs/html/meson.build b/docs/html/meson.build index b0ca400d08..83dee91ec5 100644 --- a/docs/html/meson.build +++ b/docs/html/meson.build @@ -1,16 +1,3 @@ -apipng = [ - 'home.png', - 'left.png', - 'right.png', - 'up.png', -] - -install_data(apipng, install_dir: docs_html_dir / 'html') - -foreach file : apipng - install_web_files += '@0@:@1@'.format(meson.current_source_dir() / file, docs_html_dir / 'html') -endforeach - docs_html_gen = [] docs_html_dep = [] diff --git a/docs/html/right.png b/docs/html/right.png deleted file mode 100644 index 92832e3a4566e59d6e4092010e08d28f3be3a68d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 472 zcmV;}0Vn>6P)<h;3K|Lk000e1NJLTq000;O000;W1^@s6;CDUv00006VoOIv0RI60 z0RN!9r;`8x010qNS#tmY3labT3lag+-G2N4000McNliru(g+^~G7L#2!94%~0cA-< zK~#90t&|~e!ax{?pDrgVDi9MB6HPEA7{mku!6Xj9KQVq4qIOATMG<w7Ol%GT$tIT6 zG#P^AouJJQwnDqzo1D3P_df5J`|hBHB;B^DZ(}@^w9!GSq#M_OSd#KQFBy7q3XzmZ zQor9<nx^g{6(9^l1wr5*VgrD`K_uNtib}K7mD_;U5J^F0a!xj&Da0!QV<1_rR?KFz z+8|k$vD@vA_JSZFj$=ln5x^^O?|I()X$NCTN|NL#VbgW4ldIaeEmRZ*lgWg|Vgb+t zVoAO;fDOsA3}66EodW9Q3{YM6a5#j+Wj{Fs)J#$VVC+KQ_X)$W)@ZxkvfuBUnEx2l zYe}DNADS`d;zKh4p67i?ngWl2|4aA*&^bD24D<Q?eDbD}w6r@g#wd!SD*3w6XLkXx zt^g<IZ<2cdGPeQUZr8ne33!&I<#OrXyaYU0!?bZ~Zb5qGuiLp?{jD!|Y5)O~pG*G$ O0000<MNUMnLSTZ|2*tJl diff --git a/docs/html/up.png b/docs/html/up.png deleted file mode 100644 index 85b3e2a2755fece72d0d09fbf1cf28d51fa71077..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 406 zcmeAS@N?(olHy`uVBq!ia0vp^5+KaM1|%Pp+x`GjY)RhkE)4%caKYZ?lYt_f1s;*b z3=G^tAk28_ZrvZCAbW|YuPgf{4tZ81y*aK8HyIchl|5Y?Ln`LHoowrM#DT$We|~2y zm!kHPIYzBV#iFCm$l5qa=|7aUX_&jTHR3kct+f-3dJW1pZtj?HsP%l7!S0-YWnmjW zI3~>Cd4HCN^TYHBC0dz3r5|}*T3c5!K}0^NPTey!^rYo;W&eW{b1SE%dR-1ljcju- zJITo5P_e{cPDWDszO|97o#m$fni3V4d%~7^?0HU4-k!+X`e~w55Q}HA=c?CM9`EK` z^o5GF_RsnG`ey+9wOf8O4bzg>7W<vEH1&PFe460NtxLEWt}{HFJO2hpk73;owgT5r zscZ}??>*;jU~M?g`OZAA$mNp|Lz<$s+~N9!2`ir8RcClo$(Q~19INM~9}j;&*|enC yGd}kJak0wj?aUKd8;%}`i}SSew>!A-2iw}^5}Rh(M>+vRkipZ{&t;ucLK6U4uc96R diff --git a/docs/newapi.xsl b/docs/newapi.xsl index f2e8bd5334..d48b1fbecd 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -91,28 +91,6 @@ </xsl:template> - <xsl:template name="navbar"> - <xsl:variable name="previous" select="preceding-sibling::file[1]"/> - <xsl:variable name="next" select="following-sibling::file[1]"/> - <table class="navigation" width="100%" summary="Navigation header" - cellpadding="2" cellspacing="2"> - <tr valign="middle"> - <xsl:if test="$previous"> - <td><a accesskey="p" href="libvirt-{$previous/@name}.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></img></a></td> - <th align="left"><a href="libvirt-{$previous/@name}.html"><xsl:value-of select="$previous/@name"/></a></th> - </xsl:if> - <td><a accesskey="u" href="{$indexfile}"><img src="up.png" width="24" height="24" border="0" alt="Up"></img></a></td> - <th align="left"><a href="{$indexfile}">API documentation</a></th> - <td><a accesskey="h" href="../{$indexfile}"><img src="home.png" width="24" height="24" border="0" alt="Home"></img></a></td> - <th align="center"><a href="../{$indexfile}">The virtualization API</a></th> - <xsl:if test="$next"> - <th align="right"><a href="libvirt-{$next/@name}.html"><xsl:value-of select="$next/@name"/></a></th> - <td><a accesskey="n" href="libvirt-{$next/@name}.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></img></a></td> - </xsl:if> - </tr> - </table> - </xsl:template> - <!-- This is convoluted but needed to force the current document to be the API one and not the result tree from the tokenize() result, because the keys are only defined on the main document --> -- 2.37.3
The LXC module has no exported 'Types' but the XSL template which generates the 'libvirt-libvirt-lxc.html' page would try to format it anyways. This would result in an empty non-pair version of the '<pre>' tag to be used in the page, which didn't render well with modern browsers for some reason. All following sections would become children of the non-pair <pre>. Fix the XSL template to not generate empty 'Types' or 'Functions' sections similarly to how we do with 'Macros'. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/newapi.xsl | 48 ++++++++++++++++++++++++++++-------------------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index d48b1fbecd..7b0085930f 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -756,18 +756,22 @@ </xsl:apply-templates> </pre> </xsl:if> - <h3><a href="#types">Types</a></h3> - <pre class="api"> - <xsl:apply-templates select="exports[@type='typedef']" mode="toc"> - <xsl:sort select='@symbol'/> - </xsl:apply-templates> - </pre> - <h3><a href="#functions">Functions</a></h3> - <pre class="api"> - <xsl:apply-templates select="exports[@type='function']" mode="toc"> - <xsl:sort select='@symbol'/> - </xsl:apply-templates> - </pre> + <xsl:if test="count(exports[@type='typedef']) > 0"> + <h3><a href="#types">Types</a></h3> + <pre class="api"> + <xsl:apply-templates select="exports[@type='typedef']" mode="toc"> + <xsl:sort select='@symbol'/> + </xsl:apply-templates> + </pre> + </xsl:if> + <xsl:if test="count(exports[@type='function']) > 0"> + <h3><a href="#functions">Functions</a></h3> + <pre class="api"> + <xsl:apply-templates select="exports[@type='function']" mode="toc"> + <xsl:sort select='@symbol'/> + </xsl:apply-templates> + </pre> + </xsl:if> <h2>Description</h2> @@ -777,14 +781,18 @@ <xsl:sort select='@symbol'/> </xsl:apply-templates> </xsl:if> - <h3><a id="types">Types</a></h3> - <xsl:apply-templates select="exports[@type='typedef']"> - <xsl:sort select='@symbol'/> - </xsl:apply-templates> - <h3><a id="functions">Functions</a></h3> - <xsl:apply-templates select="exports[@type='function']"> - <xsl:sort select='@symbol'/> - </xsl:apply-templates> + <xsl:if test="count(exports[@type='typedef']) > 0"> + <h3><a id="types">Types</a></h3> + <xsl:apply-templates select="exports[@type='typedef']"> + <xsl:sort select='@symbol'/> + </xsl:apply-templates> + </xsl:if> + <xsl:if test="count(exports[@type='function']) > 0"> + <h3><a id="functions">Functions</a></h3> + <xsl:apply-templates select="exports[@type='function']"> + <xsl:sort select='@symbol'/> + </xsl:apply-templates> + </xsl:if> </body> </html> </xsl:template> -- 2.37.3
When building the top level description from a header file the 'parseTopComment' method of the 'CParser' would include all trailing lines into the <description> field. This was designed to concatenate multi-line descriptions, but unfortunately in all cases also included the Copyright statement which followed. Explicitly end the scanning of the header on a line which starts with 'Copyright (C)' and truncate the spaces from the end of the last item. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- scripts/apibuild.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index c232b4e2c8..4ded66bc02 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -721,6 +721,14 @@ class CParser: item = m.group(1) line = m.group(2).lstrip() + # don't include the Copyright in the last 'item' + if line.startswith("Copyright (C)"): + # truncate any whitespace originating from newlines + # before the Copyright + if item: + res[item] = res[item].rstrip() + break + if item: if item in res: res[item] = res[item] + " " + line -- 2.37.3
On a Thursday in 2022, Peter Krempa wrote:
When building the top level description from a header file the 'parseTopComment' method of the 'CParser' would include all trailing lines into the <description> field. This was designed to concatenate multi-line descriptions, but unfortunately in all cases also included the Copyright statement which followed.
Explicitly end the scanning of the header on a line which starts with 'Copyright (C)' and truncate the spaces from the end of the last item.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- scripts/apibuild.py | 8 ++++++++ 1 file changed, 8 insertions(+)
diff --git a/scripts/apibuild.py b/scripts/apibuild.py index c232b4e2c8..4ded66bc02 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -721,6 +721,14 @@ class CParser: item = m.group(1) line = m.group(2).lstrip()
+ # don't include the Copyright in the last 'item' + if line.startswith("Copyright (C)"): + # truncate any whitespace originating from newlines + # before the Copyright
double space Jano
Fix the main links in docs.rst main page to go to the full docs rather than prompting one more click to the index page. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/docs.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs.rst b/docs/docs.rst index de08a778dc..a826bd128c 100644 --- a/docs/docs.rst +++ b/docs/docs.rst @@ -72,9 +72,9 @@ Application development `secret <html/libvirt-libvirt-secret.html>`__, `storage <html/libvirt-libvirt-storage.html>`__, `stream <html/libvirt-libvirt-stream.html>`__ and - `admin <html/index-admin.html>`__, - `QEMU <html/index-qemu.html>`__, - `LXC <html/index-lxc.html>`__ libs + `admin <html/libvirt-libvirt-admin.html>`__, + `QEMU <html/libvirt-libvirt-qemu.html>`__, + `LXC <html/libvirt-libvirt-lxc.html>`__ libs `Language bindings and API modules <bindings.html>`__ Bindings of the libvirt API for -- 2.37.3
The index page only really makes sense for the top level directory. The specific index files are unreferenced since last commit. Drop them. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/html/meson.build | 3 +-- docs/newapi.xsl | 28 +++++++++++++++------------- 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/html/meson.build b/docs/html/meson.build index 83dee91ec5..b18a8ccb5f 100644 --- a/docs/html/meson.build +++ b/docs/html/meson.build @@ -28,6 +28,7 @@ index_api_gen = custom_target( xsltproc_prog, '--nonet', '-o', docs_builddir, '--stringparam', 'builddir', meson.project_build_root(), '--stringparam', 'timestamp', docs_timestamp, + '--stringparam', 'indexfile', 'index.html', '@INPUT@', ], install: true, @@ -48,14 +49,12 @@ foreach name : [ 'admin', 'lxc', 'qemu' ] get_variable('docs_@0@_api_xml'.format(name)), ], output: [ - 'index-@0@.html'.format(name), 'libvirt-libvirt-@0@.html'.format(name), ], command: [ xsltproc_prog, '--nonet', '-o', docs_builddir, '--stringparam', 'builddir', meson.project_build_root(), '--stringparam', 'timestamp', docs_timestamp, - '--stringparam', 'indexfile', 'index-@0@.html'.format(name), '@INPUT@', ], install: true, diff --git a/docs/newapi.xsl b/docs/newapi.xsl index 7b0085930f..3de603bb00 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -22,7 +22,7 @@ <!-- Build keys for all symbols --> <xsl:key name="symbols" match="/api/symbols/*" use="@name"/> - <xsl:param name="indexfile" select="'index.html'"/> + <xsl:param name="indexfile" select="''"/> <!-- the target directory for the HTML output --> <xsl:variable name="htmldir">html</xsl:variable> @@ -823,18 +823,20 @@ <xsl:template match="/"> <!-- Save the main index.html as well as a couple of copies --> - <xsl:variable name="mainpage"> - <xsl:call-template name="mainpage"/> - </xsl:variable> - <xsl:document - href="{concat($htmldir, '/', $indexfile)}" - method="xml" - indent="yes" - encoding="UTF-8"> - <xsl:apply-templates select="exsl:node-set($mainpage)" mode="page"> - <xsl:with-param name="timestamp" select="$timestamp"/> - </xsl:apply-templates> - </xsl:document> + <xsl:if test="$indexfile != ''"> + <xsl:variable name="mainpage"> + <xsl:call-template name="mainpage"/> + </xsl:variable> + <xsl:document + href="{concat($htmldir, '/', $indexfile)}" + method="xml" + indent="yes" + encoding="UTF-8"> + <xsl:apply-templates select="exsl:node-set($mainpage)" mode="page"> + <xsl:with-param name="timestamp" select="$timestamp"/> + </xsl:apply-templates> + </xsl:document> + </xsl:if> <xsl:for-each select="/api/files/file"> <xsl:variable name="subpage"> -- 2.37.3
On a Thursday in 2022, Peter Krempa wrote:
This series cleans up some cruft unused for very long time, fixes the reference page for LXC API:
Broken (until this patchset is merged): https://www.libvirt.org/html/libvirt-libvirt-lxc.html
Fixed: https://pipo.sk.gitlab.io/-/libvirt/-/jobs/3268983196/artifacts/website/html...
Removes pointless copy of the LGPL license at the top of the API refernece files such as:
https://www.libvirt.org/html/libvirt-libvirt-qemu.html
and removes the pointless specific index files such as:
https://www.libvirt.org/html/index-qemu.html
Peter Krempa (5): docs: xsl: newapi: Remove unused 'navbar' template docs: xsl: Don't format empty sections in API manual apibuild: Don't include the Copyright in the <description> of a module docs: Link directly to admin|qemu|lxc API reference pages docs: xsl: Don't generate pointless index pages for qemu/admin/lxc API
docs/docs.rst | 6 +-- docs/html/home.png | Bin 654 -> 0 bytes docs/html/left.png | Bin 459 -> 0 bytes docs/html/meson.build | 16 +------ docs/html/right.png | Bin 472 -> 0 bytes docs/html/up.png | Bin 406 -> 0 bytes docs/newapi.xsl | 98 ++++++++++++++++++------------------------ scripts/apibuild.py | 8 ++++ 8 files changed, 55 insertions(+), 73 deletions(-) delete mode 100644 docs/html/home.png delete mode 100644 docs/html/left.png delete mode 100644 docs/html/right.png delete mode 100644 docs/html/up.png
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
participants (2)
-
Ján Tomko -
Peter Krempa