[libvirt] [PATCH] docs: remove devhelp API docs

Daniel P. Berrangé posted 1 patch 2 weeks ago
Failed in applying to current master (apply log)
docs/Makefile.am         |  38 +--
docs/devhelp/devhelp.xsl | 131 ---------
docs/devhelp/home.png    | Bin 654 -> 0 bytes
docs/devhelp/html.xsl    | 573 ---------------------------------------
docs/devhelp/left.png    | Bin 459 -> 0 bytes
docs/devhelp/right.png   | Bin 472 -> 0 bytes
docs/devhelp/style.css   |  66 -----
docs/devhelp/up.png      | Bin 406 -> 0 bytes
libvirt.spec.in          |   8 -
9 files changed, 1 insertion(+), 815 deletions(-)
delete mode 100644 docs/devhelp/devhelp.xsl
delete mode 100644 docs/devhelp/home.png
delete mode 100644 docs/devhelp/html.xsl
delete mode 100644 docs/devhelp/left.png
delete mode 100644 docs/devhelp/right.png
delete mode 100644 docs/devhelp/style.css
delete mode 100644 docs/devhelp/up.png

[libvirt] [PATCH] docs: remove devhelp API docs

Posted by Daniel P. Berrangé 2 weeks ago
We currently generate two completely separate API references for the
libvirt public API. One at 'docs/html/' and one at 'docs/devhelp/'.
Both are published on the website, but we only link to content in
the 'docs/html/' pages.

Both are installed in the libvirt-docs sub-RPM, with a full copy
of the website including 'docs/html/' in /usr/share/docs/libvirt-docs,
while the 'docs/devhelp/' content goes to /usr/share/gtk-doc/. The
latter was broken for years until:

  commit ca6f602546cb28658db05f29bc840e04d22d0947
  Author: Andrea Bolognani <abologna@redhat.com>
  Date:   Fri May 10 14:54:52 2019 +0200

    docs: Introduce $(devhelphtml_generated)

    Our XSLT magic generates one Devhelp-compatible HTML file
    per documentation module, but so far we have only shipped
    and installed documentation for virterror.

    Now that we have $(modules), however, we can generate the
    list of files the same way we do for regular documentation
    and make sure we always ship and install everything.

That this bug went unnoticed for so long is a sign of how few
people are using the devhelp docs. The only commits to the devhelp
code since it was first introduced have been fixing various build
problems that hit.

The only obvious difference between the two sets of docs is the CSS
styling in use. Overall devhelp does not look compelling enough to
justify having two duplicated sets of API docs. Eliminating it will
reduce the amount of XSL code we are carrying in the tree which is
an attractive benefit.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 docs/Makefile.am         |  38 +--
 docs/devhelp/devhelp.xsl | 131 ---------
 docs/devhelp/home.png    | Bin 654 -> 0 bytes
 docs/devhelp/html.xsl    | 573 ---------------------------------------
 docs/devhelp/left.png    | Bin 459 -> 0 bytes
 docs/devhelp/right.png   | Bin 472 -> 0 bytes
 docs/devhelp/style.css   |  66 -----
 docs/devhelp/up.png      | Bin 406 -> 0 bytes
 libvirt.spec.in          |   8 -
 9 files changed, 1 insertion(+), 815 deletions(-)
 delete mode 100644 docs/devhelp/devhelp.xsl
 delete mode 100644 docs/devhelp/home.png
 delete mode 100644 docs/devhelp/html.xsl
 delete mode 100644 docs/devhelp/left.png
 delete mode 100644 docs/devhelp/right.png
 delete mode 100644 docs/devhelp/style.css
 delete mode 100644 docs/devhelp/up.png

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 1cdb584b0b..7a5d3450fc 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -17,7 +17,6 @@
 ## <http://www.gnu.org/licenses/>.
 
 HTML_DIR = $(docdir)/html
-DEVHELP_DIR=$(datadir)/gtk-doc/html/libvirt
 
 modules = \
 	libvirt-common \
@@ -50,16 +49,6 @@ apipng = \
   html/home.png \
   html/right.png
 
-devhelphtml = \
-  devhelp/libvirt.devhelp \
-  devhelp/index.html \
-  devhelp/general.html \
-  $(devhelphtml_generated)
-
-devhelphtml_generated = \
-	$(addprefix devhelp/libvirt-,$(addsuffix .html,$(modules))) \
-	$(NULL)
-
 css = \
   generic.css \
   libvirt.css \
@@ -84,16 +73,6 @@ fonts = \
   fonts/overpass-mono-semibold.woff \
   fonts/overpass-regular.woff
 
-devhelppng = \
-  devhelp/home.png \
-  devhelp/left.png \
-  devhelp/right.png \
-  devhelp/up.png
-
-devhelpcss = devhelp/style.css
-
-devhelpxsl = devhelp/devhelp.xsl devhelp/html.xsl
-
 logofiles = \
   logos/logo-base.svg \
   logos/logo-square.svg \
@@ -188,7 +167,6 @@ EXTRA_DIST= \
   site.xsl subsite.xsl newapi.xsl page.xsl \
   wrapstring.xsl \
   $(dot_html) $(dot_html_in) $(gif) $(apihtml) $(apipng) \
-  $(devhelphtml) $(devhelppng) $(devhelpcss) $(devhelpxsl) \
   $(xml) $(qemu_xml) $(lxc_xml) $(admin_xml) $(fig) $(png) $(css) \
   $(javascript) $(logofiles) \
   $(internals_html_in) $(internals_html) $(fonts) \
@@ -206,7 +184,6 @@ $(srcdir)/aclperms.htmlinc: $(top_srcdir)/src/access/viraccessperm.h \
 MAINTAINERCLEANFILES = \
   $(addprefix $(srcdir)/,$(dot_html)) \
   $(addprefix $(srcdir)/,$(apihtml)) \
-  $(addprefix $(srcdir)/,$(devhelphtml)) \
   $(addprefix $(srcdir)/,$(internals_html)) \
   $(addprefix $(srcdir)/,$(kbase_html)) \
   $(srcdir)/hvsupport.html.in $(srcdir)/aclperms.htmlinc
@@ -226,7 +203,7 @@ lxc_api: $(srcdir)/libvirt-lxc-api.xml $(srcdir)/libvirt-lxc-refs.xml
 admin_api: $(srcdir)/libvirt-admin-api.xml $(srcdir)/libvirt-admin-refs.xml
 
 web: $(dot_html) $(internals_html) $(kbase_html) \
-	html/index.html devhelp/index.html
+	html/index.html
 
 hvsupport.html: $(srcdir)/hvsupport.html.in
 
@@ -284,12 +261,6 @@ html/index.html: libvirt-api.xml newapi.xsl page.xsl $(APIBUILD_STAMP)
 	  $(srcdir)/newapi.xsl $(srcdir)/libvirt-api.xml && \
 	  $(XMLLINT) --nonet --noout $(srcdir)/html/*.html
 
-$(addprefix $(srcdir)/,$(devhelphtml)): $(srcdir)/libvirt-api.xml $(devhelpxsl)
-	$(AM_V_GEN)$(XSLTPROC) --stringparam timestamp $(timestamp) \
-	  --nonet -o $(srcdir)/devhelp/ \
-	  $(top_srcdir)/docs/devhelp/devhelp.xsl $(srcdir)/libvirt-api.xml
-
-
 python_generated_files = \
 		$(srcdir)/html/libvirt-libvirt-lxc.html \
 		$(srcdir)/html/libvirt-libvirt-qemu.html \
@@ -388,10 +359,6 @@ install-data-local:
 	$(mkinstalldirs) $(DESTDIR)$(HTML_DIR)/kbase
 	for f in $(kbase_html); do \
 	  $(INSTALL) -m 0644 $(srcdir)/$$f $(DESTDIR)$(HTML_DIR)/kbase; done
-	$(mkinstalldirs) $(DESTDIR)$(DEVHELP_DIR)
-	for file in $(devhelphtml) $(devhelppng) $(devhelpcss); do \
-	    $(INSTALL) -m 0644 $(srcdir)/$${file} $(DESTDIR)$(DEVHELP_DIR) ; \
-	done
 	$(mkinstalldirs) $(DESTDIR)$(HTML_DIR)/fonts
 	for f in $(fonts); do \
 	  $(INSTALL) -m 0644 $(srcdir)/$$f $(DESTDIR)$(HTML_DIR)/fonts; \
@@ -415,6 +382,3 @@ uninstall-local:
 	for f in $(kbase_html); do \
 	  rm -f $(DESTDIR)$(HTML_DIR)/$$f; \
 	done
-	for f in $(devhelphtml) $(devhelppng) $(devhelpcss); do \
-	  rm -f $(DESTDIR)$(DEVHELP_DIR)/$$(basename $$f); \
-	done
diff --git a/docs/devhelp/devhelp.xsl b/docs/devhelp/devhelp.xsl
deleted file mode 100644
index 17a980c73a..0000000000
--- a/docs/devhelp/devhelp.xsl
+++ /dev/null
@@ -1,131 +0,0 @@
-<?xml version="1.0"?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
-		xmlns="http://www.devhelp.net/book"
-		xmlns:exsl="http://exslt.org/common"
-		xmlns:str="http://exslt.org/strings"
-		extension-element-prefixes="exsl str"
-		exclude-result-prefixes="exsl str">
-  <!-- The stylesheet for the html pages -->
-  <xsl:import href="html.xsl"/>
-
-  <xsl:output method="xml" encoding="UTF-8" indent="yes"/>
-
-  <!-- Build keys for all symbols -->
-  <xsl:key name="symbols" match="/api/symbols/*" use="@name"/>
-
-  <xsl:template match="/">
-    <xsl:document xmlns="http://www.devhelp.net/book" href="libvirt.devhelp"
-                  method="xml" encoding="UTF-8" indent="yes">
-      <xsl:apply-templates/>
-    </xsl:document>
-  </xsl:template>
-
-  <xsl:template match="/api">
-    <book title="{@name} Reference Manual" link="index.html" author="" name="{@name}">
-      <xsl:apply-templates select="files"/>
-      <xsl:apply-templates select="symbols"/>
-    </book>
-    <xsl:call-template name="generate_index"/>
-    <xsl:call-template name="generate_general"/>
-  </xsl:template>
-  <xsl:template match="/api/files">
-    <chapters>
-      <sub name="API" link="general.html">
-        <xsl:apply-templates select="file"/>
-      </sub>
-    </chapters>
-  </xsl:template>
-  <xsl:template match="/api/files/file">
-    <xsl:variable name="module" select="@name"/>
-    <xsl:variable name="prev" select="string(preceding-sibling::file[position()=1]/@name)"/>
-    <xsl:variable name="next" select="string(following-sibling::file[position()=1]/@name)"/>
-    <sub name="{@name}" link="libvirt-{@name}.html"/>
-    <xsl:document xmlns="" href="libvirt-{@name}.html" method="xml" indent="yes" encoding="UTF-8">
-      <html>
-        <head>
-	  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
-	  <title><xsl:value-of select="concat(@name, ': ', summary)"/></title>
-	  <meta name="generator" content="Libvirt devhelp stylesheet"/>
-	  <link rel="start" href="index.html" title="libvirt Reference Manual"/>
-	  <link rel="up" href="general.html" title="API"/>
-	  <link rel="stylesheet" href="style.css" type="text/css"/>
-	  <link rel="chapter" href="general.html" title="API"/>
-        </head>
-	<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-
-          <table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
-	    <tr valign="middle">
-	      <xsl:if test="$prev != ''">
-		<td><a accesskey="p" href="libvirt-{$prev}.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"/></a></td>
-	      </xsl:if>
-              <td><a accesskey="u" href="general.html"><img src="up.png" width="24" height="24" border="0" alt="Up"/></a></td>
-              <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"/></a></td>
-	      <xsl:if test="$next != ''">
-		<td><a accesskey="n" href="libvirt-{$next}.html"><img src="right.png" width="24" height="24" border="0" alt="Next"/></a></td>
-	      </xsl:if>
-              <th width="100%" align="center">libvirt Reference Manual</th>
-            </tr>
-	  </table>
-	  <h2><span class="refentrytitle"><xsl:value-of select="@name"/></span></h2>
-	  <p><xsl:value-of select="@name"/> - <xsl:value-of select="summary"/></p>
-	  <p><xsl:value-of select="description"/></p>
-	  <xsl:if test="deprecated">
-	    <p> WARNING: this module is deprecated !</p>
-	  </xsl:if>
-	  <div class="refsynopsisdiv">
-	  <h2>Synopsis</h2>
-	  <pre class="synopsis">
-	    <xsl:apply-templates mode="synopsis" select="exports"/>
-	  </pre>
-	  </div>
-	  <div class="refsect1" lang="en">
-	  <h2>Description</h2>
-	  </div>
-	  <div class="refsect1" lang="en">
-	  <h2>Details</h2>
-	  <div class="refsect2" lang="en">
-	    <xsl:apply-templates mode="details" select="/api/symbols/macro[@file=$module]"/>
-	    <xsl:apply-templates mode="details" select="/api/symbols/typedef[@file=$module] | /api/symbols/struct[@file=$module]"/>
-	    <xsl:apply-templates mode="details" select="/api/symbols/functype[@file=$module]"/>
-	    <xsl:apply-templates mode="details" select="/api/symbols/variable[@file=$module]"/>
-	    <xsl:apply-templates mode="details" select="/api/symbols/function[@file=$module]"/>
-	  </div>
-	  </div>
-	</body>
-      </html>
-    </xsl:document>
-  </xsl:template>
-  <xsl:template match="/api/symbols">
-    <functions>
-      <xsl:apply-templates select="macro"/>
-      <xsl:apply-templates select="enum"/>
-      <xsl:apply-templates select="typedef"/>
-      <xsl:apply-templates select="struct"/>
-      <xsl:apply-templates select="functype"/>
-      <xsl:apply-templates select="variable"/>
-      <xsl:apply-templates select="function"/>
-    </functions>
-  </xsl:template>
-  <xsl:template match="/api/symbols/functype">
-    <function name="{@name}" link="libvirt-{@file}.html#{@name}"/>
-  </xsl:template>
-  <xsl:template match="/api/symbols/function">
-    <function name="{@name} ()" link="libvirt-{@file}.html#{@name}"/>
-  </xsl:template>
-  <xsl:template match="/api/symbols/typedef">
-    <function name="{@name}" link="libvirt-{@file}.html#{@name}"/>
-  </xsl:template>
-  <xsl:template match="/api/symbols/enum">
-    <function name="{@name}" link="libvirt-{@file}.html#{@name}"/>
-  </xsl:template>
-  <xsl:template match="/api/symbols/struct">
-    <function name="{@name}" link="libvirt-{@file}.html#{@name}"/>
-  </xsl:template>
-  <xsl:template match="/api/symbols/macro">
-    <function name="{@name}" link="libvirt-{@file}.html#{@name}"/>
-  </xsl:template>
-  <xsl:template match="/api/symbols/variable">
-    <function name="{@name}" link="libvirt-{@file}.html#{@name}"/>
-  </xsl:template>
-
-</xsl:stylesheet>
diff --git a/docs/devhelp/home.png b/docs/devhelp/home.png
deleted file mode 100644
index 17003611d9..0000000000
Binary files a/docs/devhelp/home.png and /dev/null differ
diff --git a/docs/devhelp/html.xsl b/docs/devhelp/html.xsl
deleted file mode 100644
index 587cbfc1a9..0000000000
--- a/docs/devhelp/html.xsl
+++ /dev/null
@@ -1,573 +0,0 @@
-<?xml version="1.0"?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
-		xmlns:exsl="http://exslt.org/common"
-		xmlns:str="http://exslt.org/strings"
-		extension-element-prefixes="exsl str"
-		exclude-result-prefixes="exsl str">
-  <xsl:output method="xml" encoding="UTF-8" indent="yes"/>
-
-  <!-- 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 -->
-  <xsl:template mode="dumptoken" match='*'>
-    <xsl:param name="token"/>
-    <xsl:variable name="ref" select="key('symbols', $token)"/>
-    <xsl:choose>
-      <xsl:when test="$ref">
-        <a href="libvirt-{$ref/@file}.html#{$ref/@name}"><xsl:value-of select="$token"/></a>
-      </xsl:when>
-      <xsl:otherwise>
-        <xsl:value-of select="$token"/>
-      </xsl:otherwise>
-    </xsl:choose>
-  </xsl:template>
-
-  <!-- dumps a string, making cross-reference links -->
-  <xsl:template name="dumptext">
-    <xsl:param name="text"/>
-    <xsl:variable name="ctxt" select='.'/>
-    <!-- <xsl:value-of select="$text"/> -->
-    <xsl:for-each select="str:tokenize($text, ' &#9;')">
-      <xsl:apply-templates select="$ctxt" mode='dumptoken'>
-        <xsl:with-param name="token" select="string(.)"/>
-      </xsl:apply-templates>
-      <xsl:if test="position() != last()">
-        <xsl:text> </xsl:text>
-      </xsl:if>
-    </xsl:for-each>
-  </xsl:template>
-
-<!--
-
-             The following builds the Synopsis section
-
--->
-  <xsl:template mode="synopsis" match="function">
-    <xsl:variable name="name" select="string(@name)"/>
-    <xsl:variable name="nlen" select="string-length($name)"/>
-    <xsl:variable name="tlen" select="string-length(return/@type)"/>
-    <xsl:variable name="blen" select="(($nlen + 8) - (($nlen + 8) mod 8)) + (($tlen + 8) - (($tlen + 8) mod 8))"/>
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="return/@type"/>
-    </xsl:call-template>
-    <xsl:text>&#9;</xsl:text>
-    <a href="#{@name}"><xsl:value-of select="@name"/></a>
-    <xsl:if test="$blen - 40 &lt; -8">
-      <xsl:text>&#9;</xsl:text>
-    </xsl:if>
-    <xsl:if test="$blen - 40 &lt; 0">
-      <xsl:text>&#9;</xsl:text>
-    </xsl:if>
-    <xsl:text>&#9;(</xsl:text>
-    <xsl:if test="not(arg)">
-      <xsl:text>void</xsl:text>
-    </xsl:if>
-    <xsl:for-each select="arg">
-      <xsl:call-template name="dumptext">
-        <xsl:with-param name="text" select="@type"/>
-      </xsl:call-template>
-      <xsl:text> </xsl:text>
-      <xsl:value-of select="@name"/>
-      <xsl:if test="position() != last()">
-        <xsl:text>, </xsl:text><br/>
-	<xsl:if test="$blen - 40 &gt; 8">
-	  <xsl:text>&#9;</xsl:text>
-	</xsl:if>
-	<xsl:if test="$blen - 40 &gt; 0">
-	  <xsl:text>&#9;</xsl:text>
-	</xsl:if>
-	<xsl:text>&#9;&#9;&#9;&#9;&#9; </xsl:text>
-      </xsl:if>
-    </xsl:for-each>
-    <xsl:text>);</xsl:text>
-    <xsl:text>
-</xsl:text>
-  </xsl:template>
-
-  <xsl:template mode="synopsis" match="functype">
-    <xsl:variable name="name" select="string(@name)"/>
-    <xsl:variable name="nlen" select="string-length($name)"/>
-    <xsl:variable name="tlen" select="string-length(return/@type)"/>
-    <xsl:variable name="blen" select="(($nlen + 8) - (($nlen + 8) mod 8)) + (($tlen + 8) - (($tlen + 8) mod 8))"/>
-    <xsl:text>typedef </xsl:text>
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="return/@type"/>
-    </xsl:call-template>
-    <xsl:text> </xsl:text>
-    <a href="#{@name}"><xsl:value-of select="@name"/></a>
-    <xsl:if test="$blen - 40 &lt; -8">
-      <xsl:text>&#9;</xsl:text>
-    </xsl:if>
-    <xsl:if test="$blen - 40 &lt; 0">
-      <xsl:text>&#9;</xsl:text>
-    </xsl:if>
-    <xsl:text>&#9;(</xsl:text>
-    <xsl:if test="not(arg)">
-      <xsl:text>void</xsl:text>
-    </xsl:if>
-    <xsl:for-each select="arg">
-      <xsl:call-template name="dumptext">
-        <xsl:with-param name="text" select="@type"/>
-      </xsl:call-template>
-      <xsl:text> </xsl:text>
-      <xsl:value-of select="@name"/>
-      <xsl:if test="position() != last()">
-        <xsl:text>, </xsl:text><br/>
-	<xsl:if test="$blen - 40 &gt; 8">
-	  <xsl:text>&#9;</xsl:text>
-	</xsl:if>
-	<xsl:if test="$blen - 40 &gt; 0">
-	  <xsl:text>&#9;</xsl:text>
-	</xsl:if>
-	<xsl:text>&#9;&#9;&#9;&#9;&#9; </xsl:text>
-      </xsl:if>
-    </xsl:for-each>
-    <xsl:text>);</xsl:text>
-    <xsl:text>
-</xsl:text>
-  </xsl:template>
-
-  <xsl:template mode="synopsis" match="exports[@type='function']">
-    <xsl:variable name="def" select="key('symbols',@symbol)"/>
-    <xsl:apply-templates mode="synopsis" select="$def"/>
-  </xsl:template>
-
-  <xsl:template mode="synopsis" match="exports[@type='typedef']">
-    <xsl:text>typedef </xsl:text>
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="string(key('symbols',@symbol)/@type)"/>
-    </xsl:call-template>
-    <xsl:text> </xsl:text>
-    <a href="#{@symbol}"><xsl:value-of select="@symbol"/></a>
-    <xsl:text>;
-</xsl:text>
-  </xsl:template>
-
-  <xsl:template mode="synopsis" match="exports[@type='macro']">
-    <xsl:variable name="def" select="key('symbols',@symbol)"/>
-    <xsl:text>#define </xsl:text>
-    <a href="#{@symbol}"><xsl:value-of select="@symbol"/></a>
-    <xsl:if test="$def/arg">
-      <xsl:text>(</xsl:text>
-      <xsl:for-each select="$def/arg">
-        <xsl:value-of select="@name"/>
-	<xsl:if test="position() != last()">
-	  <xsl:text>, </xsl:text>
-	</xsl:if>
-      </xsl:for-each>
-      <xsl:text>)</xsl:text>
-    </xsl:if>
-    <xsl:text>;
-</xsl:text>
-  </xsl:template>
-  <xsl:template mode="synopsis" match="exports[@type='enum']">
-  </xsl:template>
-  <xsl:template mode="synopsis" match="exports[@type='struct']">
-  </xsl:template>
-
-<!--
-
-             The following builds the Details section
-
--->
-  <xsl:template mode="details" match="struct">
-    <xsl:variable name="name" select="string(@name)"/>
-    <div class="refsect2" lang="en">
-    <h3><a id="{$name}">Structure </a><xsl:value-of select="$name"/></h3>
-    <pre class="programlisting">
-    <xsl:value-of select="@type"/><xsl:text> {
-</xsl:text>
-    <xsl:if test="not(field)">
-      <xsl:text>The content of this structure is not made public by the API.
-</xsl:text>
-    </xsl:if>
-    <xsl:for-each select="field">
-        <xsl:text>    </xsl:text>
-	<xsl:call-template name="dumptext">
-	  <xsl:with-param name="text" select="@type"/>
-	</xsl:call-template>
-	<xsl:text>&#9;</xsl:text>
-	<xsl:value-of select="@name"/>
-	<xsl:if test="@info != ''">
-	  <xsl:text>&#9;: </xsl:text>
-	  <xsl:call-template name="dumptext">
-	    <xsl:with-param name="text" select="substring(@info, 1, 70)"/>
-	  </xsl:call-template>
-	</xsl:if>
-	<xsl:text>
-</xsl:text>
-    </xsl:for-each>
-    <xsl:text>} </xsl:text>
-    <xsl:value-of select="$name"/>
-    <xsl:text>;
-</xsl:text>
-    </pre>
-    <p>
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="info"/>
-    </xsl:call-template>
-    </p><xsl:text>
-</xsl:text>
-    </div><hr/>
-  </xsl:template>
-
-  <xsl:template mode="details" match="typedef[@type != 'enum']">
-    <xsl:variable name="name" select="string(@name)"/>
-    <div class="refsect2" lang="en">
-    <h3><a id="{$name}">Typedef </a><xsl:value-of select="$name"/></h3>
-    <pre class="programlisting">
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="string(@type)"/>
-    </xsl:call-template>
-    <xsl:text> </xsl:text>
-    <xsl:value-of select="$name"/>
-    <xsl:text>;
-</xsl:text>
-    </pre>
-    <p>
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="info"/>
-    </xsl:call-template>
-    </p><xsl:text>
-</xsl:text>
-    </div><hr/>
-  </xsl:template>
-
-  <xsl:template mode="details" match="variable">
-    <xsl:variable name="name" select="string(@name)"/>
-    <div class="refsect2" lang="en">
-    <h3><a id="{$name}">Variable </a><xsl:value-of select="$name"/></h3>
-    <pre class="programlisting">
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="string(@type)"/>
-    </xsl:call-template>
-    <xsl:text> </xsl:text>
-    <xsl:value-of select="$name"/>
-    <xsl:text>;
-</xsl:text>
-    </pre>
-    <p>
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="info"/>
-    </xsl:call-template>
-    </p><xsl:text>
-</xsl:text>
-    </div><hr/>
-  </xsl:template>
-
-  <xsl:template mode="details" match="typedef[@type = 'enum']">
-    <xsl:variable name="name" select="string(@name)"/>
-    <div class="refsect2" lang="en">
-    <h3><a id="{$name}">Enum </a><xsl:value-of select="$name"/></h3>
-    <pre class="programlisting">
-    <xsl:text>enum </xsl:text>
-    <a href="#{$name}"><xsl:value-of select="$name"/></a>
-    <xsl:text> {
-</xsl:text>
-    <xsl:for-each select="/api/symbols/enum[@type=$name]">
-      <xsl:sort select="@value" data-type="number" order="ascending"/>
-      <xsl:text>    </xsl:text>
-      <a id="{@name}"><xsl:value-of select="@name"/></a>
-      <xsl:if test="@value">
-        <xsl:text> = </xsl:text>
-	<xsl:value-of select="@value"/>
-      </xsl:if>
-      <xsl:if test="@info">
-        <xsl:text> /* </xsl:text>
-	<xsl:value-of select="@info"/>
-        <xsl:text> */</xsl:text>
-      </xsl:if>
-      <xsl:text>
-</xsl:text>
-    </xsl:for-each>
-    <xsl:text>};
-</xsl:text>
-    </pre>
-    <p>
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="info"/>
-    </xsl:call-template>
-    </p><xsl:text>
-</xsl:text>
-    </div><hr/>
-  </xsl:template>
-
-  <xsl:template mode="details" match="macro">
-    <xsl:variable name="name" select="string(@name)"/>
-    <div class="refsect2" lang="en">
-    <h3><a id="{$name}">Macro </a><xsl:value-of select="$name"/></h3>
-    <pre class="programlisting">
-    <xsl:text>#define </xsl:text>
-    <a href="#{$name}"><xsl:value-of select="$name"/></a>
-    <xsl:if test="arg">
-      <xsl:text>(</xsl:text>
-      <xsl:for-each select="arg">
-        <xsl:value-of select="@name"/>
-	<xsl:if test="position() != last()">
-	  <xsl:text>, </xsl:text>
-	</xsl:if>
-      </xsl:for-each>
-      <xsl:text>)</xsl:text>
-    </xsl:if>
-    <xsl:text>;
-</xsl:text>
-    </pre>
-    <p>
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="info"/>
-    </xsl:call-template>
-    </p>
-    <xsl:if test="arg">
-      <div class="variablelist"><table border="0"><col align="left"/><tbody>
-      <xsl:for-each select="arg">
-        <tr>
-          <td><span class="term"><i><tt><xsl:value-of select="@name"/></tt></i>:</span></td>
-	  <td>
-	    <xsl:call-template name="dumptext">
-	      <xsl:with-param name="text" select="@info"/>
-	    </xsl:call-template>
-	  </td>
-        </tr>
-      </xsl:for-each>
-      </tbody></table></div>
-    </xsl:if>
-    <xsl:text>
-</xsl:text>
-    </div><hr/>
-  </xsl:template>
-
-  <xsl:template mode="details" match="function">
-    <xsl:variable name="name" select="string(@name)"/>
-    <xsl:variable name="nlen" select="string-length($name)"/>
-    <xsl:variable name="tlen" select="string-length(return/@type)"/>
-    <xsl:variable name="blen" select="(($nlen + 8) - (($nlen + 8) mod 8)) + (($tlen + 8) - (($tlen + 8) mod 8))"/>
-    <div class="refsect2" lang="en">
-    <h3><a id="{$name}"></a><xsl:value-of select="$name"/> ()</h3>
-    <pre class="programlisting">
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="return/@type"/>
-    </xsl:call-template>
-    <xsl:text>&#9;</xsl:text>
-    <xsl:value-of select="@name"/>
-    <xsl:if test="$blen - 40 &lt; -8">
-      <xsl:text>&#9;</xsl:text>
-    </xsl:if>
-    <xsl:if test="$blen - 40 &lt; 0">
-      <xsl:text>&#9;</xsl:text>
-    </xsl:if>
-    <xsl:text>&#9;(</xsl:text>
-    <xsl:if test="not(arg)">
-      <xsl:text>void</xsl:text>
-    </xsl:if>
-    <xsl:for-each select="arg">
-      <xsl:call-template name="dumptext">
-        <xsl:with-param name="text" select="@type"/>
-      </xsl:call-template>
-      <xsl:text> </xsl:text>
-      <xsl:value-of select="@name"/>
-      <xsl:if test="position() != last()">
-        <xsl:text>, </xsl:text><br/>
-	<xsl:if test="$blen - 40 &gt; 8">
-	  <xsl:text>&#9;</xsl:text>
-	</xsl:if>
-	<xsl:if test="$blen - 40 &gt; 0">
-	  <xsl:text>&#9;</xsl:text>
-	</xsl:if>
-	<xsl:text>&#9;&#9;&#9;&#9;&#9; </xsl:text>
-      </xsl:if>
-    </xsl:for-each>
-    <xsl:text>)</xsl:text><br/>
-    <xsl:text>
-</xsl:text>
-    </pre>
-    <p>
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="info"/>
-    </xsl:call-template>
-    </p><xsl:text>
-</xsl:text>
-    <xsl:if test="arg | return/@info">
-      <div class="variablelist"><table border="0"><col align="left"/><tbody>
-      <xsl:for-each select="arg">
-        <tr>
-          <td><span class="term"><i><tt><xsl:value-of select="@name"/></tt></i>:</span></td>
-	  <td>
-	    <xsl:call-template name="dumptext">
-	      <xsl:with-param name="text" select="@info"/>
-	    </xsl:call-template>
-	  </td>
-        </tr>
-      </xsl:for-each>
-      <xsl:if test="return/@info">
-        <tr>
-          <td><span class="term"><i><tt>Returns</tt></i>:</span></td>
-	  <td>
-	    <xsl:call-template name="dumptext">
-	      <xsl:with-param name="text" select="return/@info"/>
-	    </xsl:call-template>
-	  </td>
-        </tr>
-      </xsl:if>
-      </tbody></table></div>
-    </xsl:if>
-    </div><hr/>
-  </xsl:template>
-
-  <xsl:template mode="details" match="functype">
-    <xsl:variable name="name" select="string(@name)"/>
-    <xsl:variable name="nlen" select="string-length($name)"/>
-    <xsl:variable name="tlen" select="string-length(return/@type)"/>
-    <xsl:variable name="blen" select="(($nlen + 8) - (($nlen + 8) mod 8)) + (($tlen + 8) - (($tlen + 8) mod 8))"/>
-    <div class="refsect2" lang="en">
-    <h3><a id="{$name}"></a>Function type <xsl:value-of select="$name"/> </h3>
-    <pre class="programlisting">
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="return/@type"/>
-    </xsl:call-template>
-    <xsl:text>&#9;</xsl:text>
-    <xsl:value-of select="@name"/>
-    <xsl:if test="$blen - 40 &lt; -8">
-      <xsl:text>&#9;</xsl:text>
-    </xsl:if>
-    <xsl:if test="$blen - 40 &lt; 0">
-      <xsl:text>&#9;</xsl:text>
-    </xsl:if>
-    <xsl:text>&#9;(</xsl:text>
-    <xsl:if test="not(arg)">
-      <xsl:text>void</xsl:text>
-    </xsl:if>
-    <xsl:for-each select="arg">
-      <xsl:call-template name="dumptext">
-        <xsl:with-param name="text" select="@type"/>
-      </xsl:call-template>
-      <xsl:text> </xsl:text>
-      <xsl:value-of select="@name"/>
-      <xsl:if test="position() != last()">
-        <xsl:text>, </xsl:text><br/>
-	<xsl:if test="$blen - 40 &gt; 8">
-	  <xsl:text>&#9;</xsl:text>
-	</xsl:if>
-	<xsl:if test="$blen - 40 &gt; 0">
-	  <xsl:text>&#9;</xsl:text>
-	</xsl:if>
-	<xsl:text>&#9;&#9;&#9;&#9;&#9; </xsl:text>
-      </xsl:if>
-    </xsl:for-each>
-    <xsl:text>)</xsl:text><br/>
-    <xsl:text>
-</xsl:text>
-    </pre>
-    <p>
-    <xsl:call-template name="dumptext">
-      <xsl:with-param name="text" select="info"/>
-    </xsl:call-template>
-    </p><xsl:text>
-</xsl:text>
-    <xsl:if test="arg | return/@info">
-      <div class="variablelist"><table border="0"><col align="left"/><tbody>
-      <xsl:for-each select="arg">
-        <tr>
-          <td><span class="term"><i><tt><xsl:value-of select="@name"/></tt></i>:</span></td>
-	  <td>
-	    <xsl:call-template name="dumptext">
-	      <xsl:with-param name="text" select="@info"/>
-	    </xsl:call-template>
-	  </td>
-        </tr>
-      </xsl:for-each>
-      <xsl:if test="return/@info">
-        <tr>
-          <td><span class="term"><i><tt>Returns</tt></i>:</span></td>
-	  <td>
-	    <xsl:call-template name="dumptext">
-	      <xsl:with-param name="text" select="return/@info"/>
-	    </xsl:call-template>
-	  </td>
-        </tr>
-      </xsl:if>
-      </tbody></table></div>
-    </xsl:if>
-    </div><hr/>
-  </xsl:template>
-
-<!--
-
-             The following builds the general.html page
-
--->
-  <xsl:template name="generate_general">
-    <xsl:variable name="next" select="string(/api/files/file[position()=1]/@name)"/>
-    <xsl:document xmlns="" href="general.html" method="xml" indent="yes" encoding="UTF-8">
-      <html>
-        <head>
-	  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
-	  <title><xsl:value-of select="concat(@name, ': ', summary)"/></title>
-	  <meta name="generator" content="Libvirt devhelp stylesheet"/>
-	  <link rel="start" href="index.html" title="libvirt Reference Manual"/>
-	  <link rel="up" href="index.html" title="libvirt Reference Manual"/>
-	  <link rel="stylesheet" href="style.css" type="text/css"/>
-	  <link rel="chapter" href="index.html" title="libvirt Reference Manual"/>
-        </head>
-	<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-
-          <table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
-	    <tr valign="middle">
-              <td><a accesskey="u" href="index.html"><img src="up.png" width="24" height="24" border="0" alt="Up"/></a></td>
-              <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"/></a></td>
-	      <xsl:if test="$next != ''">
-		<td><a accesskey="n" href="libvirt-{$next}.html"><img src="right.png" width="24" height="24" border="0" alt="Next"/></a></td>
-	      </xsl:if>
-              <th width="100%" align="center">libvirt Reference Manual</th>
-            </tr>
-	  </table>
-	  <h2><span class="refentrytitle">libvirt API Modules</span></h2>
-	  <p>
-	  <xsl:for-each select="/api/files/file">
-	    <a href="libvirt-{@name}.html"><xsl:value-of select="@name"/></a> - <xsl:value-of select="summary"/><br/>
-	  </xsl:for-each>
-	  </p>
-	</body>
-      </html>
-    </xsl:document>
-  </xsl:template>
-
-<!--
-
-             The following builds the index.html page
-
--->
-  <xsl:template name="generate_index">
-    <xsl:document xmlns="" href="index.html" method="xml" indent="yes" encoding="UTF-8">
-      <html>
-        <head>
-	  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
-	  <title>libvirt Reference Manual</title>
-	  <meta name="generator" content="Libvirt devhelp stylesheet"/>
-	  <link rel="stylesheet" href="style.css" type="text/css"/>
-        </head>
-	<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-
-          <table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
-	    <tr valign="middle">
-              <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"/></a></td>
-	      <td><a accesskey="n" href="general.html"><img src="right.png" width="24" height="24" border="0" alt="Next"/></a></td>
-              <th width="100%" align="center">libvirt Reference Manual</th>
-            </tr>
-	  </table>
-	  <h2><span class="refentrytitle">libvirt Reference Manual</span></h2>
-<p>Libvir is a C toolkit to interact with the virtualization capabilities of
-recent versions of Linux (and other OSes). It is free software available
-under the <a href="http://www.opensource.org/licenses/lgpl-license.html">GNU
-Lesser General Public License</a>. Virtualization of the Linux Operating
-System means the ability to run multiple instances of Operating Systems
-concurrently on a single hardware system where the basic resources are driven
-by a Linux instance. The library aim at providing long term stable C API
-initially for the <a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen
-paravirtualization</a> but should be able to integrate other virtualization
-mechanisms if needed.</p>
-	</body>
-      </html>
-    </xsl:document>
-  </xsl:template>
-
-</xsl:stylesheet>
diff --git a/docs/devhelp/left.png b/docs/devhelp/left.png
deleted file mode 100644
index 2d05b3d5b4..0000000000
Binary files a/docs/devhelp/left.png and /dev/null differ
diff --git a/docs/devhelp/right.png b/docs/devhelp/right.png
deleted file mode 100644
index 92832e3a45..0000000000
Binary files a/docs/devhelp/right.png and /dev/null differ
diff --git a/docs/devhelp/style.css b/docs/devhelp/style.css
deleted file mode 100644
index dfbb41e34c..0000000000
--- a/docs/devhelp/style.css
+++ /dev/null
@@ -1,66 +0,0 @@
-.synopsis, .classsynopsis
-{
-  background: #eeeeee;
-  border: solid 1px #aaaaaa;
-  padding: 0.5em;
-}
-.programlisting
-{
-  background: #eeeeff;
-  border: solid 1px #aaaaff;
-  padding: 0.5em;
-}
-.variablelist
-{
-  padding: 4px;
-  margin-left: 3em;
-}
-.variablelist td:first-child
-{
-  vertical-align: top;
-}
-table.navigation
-{
-  background: #ffeeee;
-  border: solid 1px #ffaaaa;
-  margin-top: 0.5em;
-  margin-bottom: 0.5em;
-}
-.navigation a
-{
-  color: #770000;
-}
-.navigation a:visited
-{
-  color: #550000;
-}
-.navigation .title
-{
-  font-size: 200%;
-}
-div.refnamediv
-{
-  margin-top: 2em;
-}
-div.gallery-float
-{
-  float: left;
-  padding: 10px;
-}
-div.gallery-float img
-{
-  border-style: none;
-}
-div.gallery-spacer
-{
-  clear: both;
-}
-a
-{
-  text-decoration: none;
-}
-a:hover
-{
-  text-decoration: underline;
-  color: #FF0000;
-}
diff --git a/docs/devhelp/up.png b/docs/devhelp/up.png
deleted file mode 100644
index 85b3e2a275..0000000000
Binary files a/docs/devhelp/up.png and /dev/null differ
diff --git a/libvirt.spec.in b/libvirt.spec.in
index dde8bf3a97..d4d2ec8db9 100644
--- a/libvirt.spec.in
+++ b/libvirt.spec.in
@@ -1528,14 +1528,6 @@ exit 0
 %doc AUTHORS ChangeLog.gz NEWS README README.md
 %doc libvirt-docs/*
 
-# API docs
-%dir %{_datadir}/gtk-doc/html/libvirt/
-%doc %{_datadir}/gtk-doc/html/libvirt/*.devhelp
-%doc %{_datadir}/gtk-doc/html/libvirt/*.html
-%doc %{_datadir}/gtk-doc/html/libvirt/*.png
-%doc %{_datadir}/gtk-doc/html/libvirt/*.css
-
-
 %files daemon
 
 %dir %attr(0700, root, root) %{_sysconfdir}/libvirt/
-- 
2.21.0

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

Re: [libvirt] [PATCH] docs: remove devhelp API docs

Posted by Andrea Bolognani 1 week ago
On Thu, 2019-09-05 at 13:34 +0100, Daniel P. Berrangé wrote:
> We currently generate two completely separate API references for the
> libvirt public API. One at 'docs/html/' and one at 'docs/devhelp/'.
> Both are published on the website, but we only link to content in
> the 'docs/html/' pages.
> 
> Both are installed in the libvirt-docs sub-RPM, with a full copy
> of the website including 'docs/html/' in /usr/share/docs/libvirt-docs,
> while the 'docs/devhelp/' content goes to /usr/share/gtk-doc/. The
> latter was broken for years until:
> 
>   commit ca6f602546cb28658db05f29bc840e04d22d0947
>   Author: Andrea Bolognani <abologna@redhat.com>
>   Date:   Fri May 10 14:54:52 2019 +0200
> 
>     docs: Introduce $(devhelphtml_generated)
> 
>     Our XSLT magic generates one Devhelp-compatible HTML file
>     per documentation module, but so far we have only shipped
>     and installed documentation for virterror.
> 
>     Now that we have $(modules), however, we can generate the
>     list of files the same way we do for regular documentation
>     and make sure we always ship and install everything.
> 
> That this bug went unnoticed for so long is a sign of how few
> people are using the devhelp docs. The only commits to the devhelp
> code since it was first introduced have been fixing various build
> problems that hit.
> 
> The only obvious difference between the two sets of docs is the CSS
> styling in use. Overall devhelp does not look compelling enough to
> justify having two duplicated sets of API docs. Eliminating it will
> reduce the amount of XSL code we are carrying in the tree which is
> an attractive benefit.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>  docs/Makefile.am         |  38 +--
>  docs/devhelp/devhelp.xsl | 131 ---------
>  docs/devhelp/home.png    | Bin 654 -> 0 bytes
>  docs/devhelp/html.xsl    | 573 ---------------------------------------
>  docs/devhelp/left.png    | Bin 459 -> 0 bytes
>  docs/devhelp/right.png   | Bin 472 -> 0 bytes
>  docs/devhelp/style.css   |  66 -----
>  docs/devhelp/up.png      | Bin 406 -> 0 bytes
>  libvirt.spec.in          |   8 -
>  9 files changed, 1 insertion(+), 815 deletions(-)

As the person who spent time fixing Devhelp support a while ago,
I'm perfectly fine dropping it. Perhaps I should have gone this
route myself in the first place :)

I don't have time to look at the patch in detail, but from a quick
look I didn't spot any obvious issues, plus if there were any I
trust Pavel would have found them during his review, so

  Reviewed-by: Andrea Bolognani <abologna@redhat.com>

-- 
Andrea Bolognani / Red Hat / Virtualization

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

Re: [libvirt] [PATCH] docs: remove devhelp API docs

Posted by Pavel Hrdina 1 week ago
On Thu, Sep 05, 2019 at 01:34:37PM +0100, Daniel P. Berrangé wrote:
> We currently generate two completely separate API references for the
> libvirt public API. One at 'docs/html/' and one at 'docs/devhelp/'.
> Both are published on the website, but we only link to content in
> the 'docs/html/' pages.
> 
> Both are installed in the libvirt-docs sub-RPM, with a full copy
> of the website including 'docs/html/' in /usr/share/docs/libvirt-docs,
> while the 'docs/devhelp/' content goes to /usr/share/gtk-doc/. The
> latter was broken for years until:
> 
>   commit ca6f602546cb28658db05f29bc840e04d22d0947
>   Author: Andrea Bolognani <abologna@redhat.com>
>   Date:   Fri May 10 14:54:52 2019 +0200
> 
>     docs: Introduce $(devhelphtml_generated)
> 
>     Our XSLT magic generates one Devhelp-compatible HTML file
>     per documentation module, but so far we have only shipped
>     and installed documentation for virterror.
> 
>     Now that we have $(modules), however, we can generate the
>     list of files the same way we do for regular documentation
>     and make sure we always ship and install everything.
> 
> That this bug went unnoticed for so long is a sign of how few
> people are using the devhelp docs. The only commits to the devhelp
> code since it was first introduced have been fixing various build
> problems that hit.
> 
> The only obvious difference between the two sets of docs is the CSS
> styling in use. Overall devhelp does not look compelling enough to
> justify having two duplicated sets of API docs. Eliminating it will
> reduce the amount of XSL code we are carrying in the tree which is
> an attractive benefit.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>  docs/Makefile.am         |  38 +--
>  docs/devhelp/devhelp.xsl | 131 ---------
>  docs/devhelp/home.png    | Bin 654 -> 0 bytes
>  docs/devhelp/html.xsl    | 573 ---------------------------------------
>  docs/devhelp/left.png    | Bin 459 -> 0 bytes
>  docs/devhelp/right.png   | Bin 472 -> 0 bytes
>  docs/devhelp/style.css   |  66 -----
>  docs/devhelp/up.png      | Bin 406 -> 0 bytes
>  libvirt.spec.in          |   8 -
>  9 files changed, 1 insertion(+), 815 deletions(-)
>  delete mode 100644 docs/devhelp/devhelp.xsl
>  delete mode 100644 docs/devhelp/home.png
>  delete mode 100644 docs/devhelp/html.xsl
>  delete mode 100644 docs/devhelp/left.png
>  delete mode 100644 docs/devhelp/right.png
>  delete mode 100644 docs/devhelp/style.css
>  delete mode 100644 docs/devhelp/up.png

Nice cleanup, it failed to apply for me but I did the same changes and
looks good.

error: cannot apply binary patch to 'docs/devhelp/home.png' without full index line
error: docs/devhelp/home.png: patch does not apply

This would probably require to use --full-index and/or --binary to
format the patch.

Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list