[libvirt PATCH v2 2/3] news: Convert to reStructuredText

Instead of storing release notes as XML and then converting them to HTML and ASCII at build time using XSLT and a custom script, we can use reStructuredText as both the source and ASCII representation and generate HTML from it using the same tooling we already use for the rest of the documentation. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- Makefile.am | 22 +- NEWS.rst | 3362 +++++++++++++++++++++++ docs/Makefile.am | 27 +- docs/libvirt.css | 15 - docs/news-ascii.xsl | 95 - docs/news-html.xsl | 106 - docs/news.rng | 72 - docs/news.xml | 5473 -------------------------------------- scripts/reformat-news.py | 102 - tests/virschematest.c | 2 - 10 files changed, 3374 insertions(+), 5902 deletions(-) create mode 100644 NEWS.rst delete mode 100644 docs/news-ascii.xsl delete mode 100644 docs/news-html.xsl delete mode 100644 docs/news.rng delete mode 100644 docs/news.xml delete mode 100755 scripts/reformat-news.py diff --git a/Makefile.am b/Makefile.am index d56deeb080..3b93170bc6 100644 --- a/Makefile.am +++ b/Makefile.am @@ -46,6 +46,7 @@ EXTRA_DIST = \ README.rst \ AUTHORS.in \ CONTRIBUTING.rst \ + NEWS.rst \ scripts/apibuild.py \ scripts/augeas-gentest.py \ build-aux/check-spacing.pl \ @@ -69,7 +70,6 @@ EXTRA_DIST = \ scripts/minimize-po.py \ scripts/mock-noinline.py \ scripts/prohibit-duplicate-header.py \ - scripts/reformat-news.py \ scripts/test-wrap-argv.py \ build-aux/syntax-check.mk \ build-aux/useless-if-before-free \ @@ -83,26 +83,6 @@ EXTRA_DIST = \ pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = libvirt.pc libvirt-qemu.pc libvirt-lxc.pc libvirt-admin.pc -NEWS: \ - $(srcdir)/docs/news.xml \ - $(srcdir)/docs/news-ascii.xsl \ - $(top_srcdir)/scripts/reformat-news.py - $(AM_V_GEN) \ - if [ -x $(XSLTPROC) ]; then \ - $(XSLTPROC) --nonet \ - $(srcdir)/docs/news-ascii.xsl \ - $(srcdir)/docs/news.xml \ - >$@-tmp \ - || { rm -f $@-tmp; exit 1; }; \ - $(RUNUTF8) $(PYTHON) $(top_srcdir)/scripts/reformat-news.py $@-tmp >$@ \ - || { rm -f $@-tmp; exit 1; }; \ - rm -f $@-tmp; \ - fi -EXTRA_DIST += \ - $(srcdir)/docs/news.xml \ - $(srcdir)/docs/news-ascii.xsl \ - $(NULL) - rpm: clean @(unset CDPATH ; $(MAKE) dist && rpmbuild -ta $(distdir).tar.xz) diff --git a/NEWS.rst b/NEWS.rst new file mode 100644 index 0000000000..e4d52a96e9 --- /dev/null +++ b/NEWS.rst @@ -0,0 +1,3362 @@ +================ +libvirt releases +================ + +This is the list of official releases for libvirt, along with an overview of +the changes introduced by each of them. + +For a more fine-grained view, use the `git log`_. + + +v6.5.0 (unreleased) +=================== + +* **New features** + +* **Improvements** + +* **Bug fixes** + + +v6.4.0 (2020-06-02) +=================== + +* **New features** + + * qemu: Add support for pvscsi controllers + + pvscsi is the VMware paravirtualized SCSI controller, which has been + supported in QEMU for a number of years. + + * cpu: Report model information for ARM CPUs + + ``virsh capabilities`` will now include information about the host CPU when + run on ARM machines. + +* **Improvements** + + * qemu: stricter validation for disk type='lun' + + The 'lun' type is meant for SCSI command passthrough, which can't be + achieved if qemu's block layer features are used. Disk type='lun' is now + allowed only when the format is 'raw' and no other block layer features are + requested. + +* **Bug fixes** + + * qemu: fixed regression in network device hotplug with new qemu versions + + Starting from QEMU-5.0 it's required to conform to strict schema when + hotplugging network devices. Libvirt didn't conform to the schema so in + versions prior to 6.4.0 network device hotplug fails in certain cases. This + version fixes it and adds stricter testing to prevent further issues. + + * remote: Look up libxl driver correctly + + This makes ``xen://`` connection URIs usable in split daemon mode. + + * systemd: Start libvirtd after firewalld/iptables services + + This solves an issue where iptables rules and chains created by libvirtd + would get removed by a service started after it. + + * network: Re-create iptables chains on firewalld restart + + firewalld resets all iptables rules and chains on restart, and this + includes deleting those created by libvirt. [...] diff --git a/docs/Makefile.am b/docs/Makefile.am index ba538e55a0..d8109bb65c 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -316,16 +316,18 @@ manpages/virkeyname-%.rst: $(top_srcdir)/src/keycodemapdb/data/keymaps.csv \ manpagesdir = $(HTML_DIR)/manpages manpages_DATA = $(manpages_html) -# Generate hvsupport.html and news.html first, since they take one extra step. +# Generate hvsupport.html first, since it takes one extra step. dot_html_generated_in = \ hvsupport.html.in \ - news.html.in + $(NULL) dot_html_in = \ $(notdir $(wildcard $(srcdir)/*.html.in)) dot_rst = \ $(notdir $(wildcard $(srcdir)/*.rst)) dot_rst_html_in = \ - $(dot_rst:%.rst=%.html.in) + $(dot_rst:%.rst=%.html.in) \ + news.html.in \ + $(NULL) dot_html = \ $(dot_html_generated_in:%.html.in=%.html) \ $(dot_html_in:%.html.in=%.html) \ @@ -405,19 +407,6 @@ hvsupport.html.in: $(top_srcdir)/scripts/hvsupport.py $(api_DATA) \ $(AM_V_GEN)$(RUNUTF8) $(PYTHON) $(top_srcdir)/scripts/hvsupport.py \ $(top_srcdir) $(top_builddir) > $@ || { rm $@ && exit 1; } -news.html.in: \ - $(srcdir)/news.xml \ - $(srcdir)/news-html.xsl - $(AM_V_GEN)$(XSLTPROC) --nonet \ - $(srcdir)/news-html.xsl \ - $(srcdir)/news.xml \ - >$@ \ - || { rm -f $@; exit 1; }; -EXTRA_DIST += \ - $(srcdir)/news.xml \ - $(srcdir)/news.rng \ - $(srcdir)/news-html.xsl - %.png: %.fig convert -rotate 90 $< $@ @@ -428,6 +417,12 @@ manpages/%.html.in: manpages/%.rst -e 's|RUNSTATEDIR|$(runstatedir)|g' | \ $(RST2HTML) --strict > $@ || { rm $@ && exit 1; } +news.html.in: $(top_srcdir)/NEWS.rst + $(AM_V_GEN)$(MKDIR_P) `dirname $@` && \ + $(RST2HTML) --strict $< > $@ || { rm $@ && exit 1; } + +CLEANFILES += news.html.in + %.html.in: %.rst $(AM_V_GEN)$(MKDIR_P) `dirname $@` && \ $(RST2HTML) --strict $< > $@ || { rm $@ && exit 1; } diff --git a/docs/libvirt.css b/docs/libvirt.css index a2c9778e03..3f0fd93089 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -560,21 +560,6 @@ td.enumvalue { color: darkred; } -ul.news-section-content { - margin-top: 0.5em; -} - -ul.news-section-content li dl dt { - margin: 0; -} - -ul.news-section-content li dl dd { - margin-left: 1em; - margin-right: 0; - margin-top: 0.5em; - margin-bottom: 0.5em; -} - .literal, code { font-family: monospace; background: #eeeeee; diff --git a/docs/news-ascii.xsl b/docs/news-ascii.xsl deleted file mode 100644 index 9f6c61a3c6..0000000000 --- a/docs/news-ascii.xsl +++ /dev/null @@ -1,95 +0,0 @@ -<?xml version="1.0"?> -<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> - <xsl:output method="text" encoding="UTF-8"/> - - <!-- This XSLT stylesheet can be applied to the XML version of the release - notes to produce a plain text document. The output document is not - formatted properly and needs to be processed further --> - - <!-- Document --> - <xsl:template match="/libvirt"> - <xsl:text>================ -libvirt releases -================ - -This is the list of official releases for libvirt, along with an overview of -the changes introduced by each of them. - -For a more fine-grained view, use the `git log`_. -</xsl:text> - <xsl:apply-templates select="release"/> - <xsl:text> - -Older libvirt releases didn't have proper release notes: if you are interested -in changes between them, you should check out docs/news-\*.html or the full git -log (see instructions in ChangeLog). - - -.. _git log: https://gitlab.com/libvirt/libvirt/-/commits/master -</xsl:text> - </xsl:template> - - <!-- Release --> - <xsl:template match="release"> - <xsl:text> - -</xsl:text> - <xsl:value-of select="@version"/> - <xsl:text> (</xsl:text> - <xsl:value-of select="@date"/> - <xsl:text>) -=================== -</xsl:text> - - <xsl:apply-templates select="section"/> - </xsl:template> - - <!-- Section --> - <xsl:template match="section"> - <xsl:text> -* **</xsl:text> - <xsl:value-of select="@title"/> - <xsl:text>** -</xsl:text> - <xsl:apply-templates select="change"/> - </xsl:template> - - <!-- Change --> - <xsl:template match="change"> - <xsl:text> -</xsl:text> - <xsl:apply-templates select="summary"/> - <xsl:apply-templates select="description"/> - </xsl:template> - - <!-- Change summary --> - <xsl:template match="summary"> - <xsl:text>- </xsl:text> - <xsl:value-of select="normalize-space()"/> - <xsl:text> -</xsl:text> - </xsl:template> - - <!-- Change description --> - <xsl:template match="description"> - <xsl:text> -</xsl:text> - <xsl:text>|</xsl:text> <!-- This will be removed when reformatting --> - <xsl:apply-templates/> - <xsl:text> -</xsl:text> - </xsl:template> - - <!-- Regular text in change description --> - <xsl:template match="description//text()"> - <xsl:value-of select="normalize-space()"/> - </xsl:template> - - <!-- <code> HTML tag in change description --> - <xsl:template match="description//code"> - <xsl:text disable-output-escaping="yes"> ``</xsl:text> - <xsl:apply-templates/> - <xsl:text disable-output-escaping="yes">`` </xsl:text> - </xsl:template> - -</xsl:stylesheet> diff --git a/docs/news-html.xsl b/docs/news-html.xsl deleted file mode 100644 index ec031c6d15..0000000000 --- a/docs/news-html.xsl +++ /dev/null @@ -1,106 +0,0 @@ -<?xml version="1.0"?> -<xsl:stylesheet version="1.0" - xmlns="http://www.w3.org/1999/xhtml" - xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> - <xsl:output method="xml" indent="yes" encoding="UTF-8"/> - - <!-- This XSLT stylesheet can be applied to the XML version of the release - notes to produce an HTML document suitable for further processing. - In particular, the final output will end up on the libvirt website --> - - <!-- Document --> - <xsl:template match="/libvirt"> - <xsl:text disable-output-escaping="yes">&lt;!DOCTYPE html&gt; -</xsl:text> - <html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - </head> - <body> - <xsl:text disable-output-escaping="yes"> - - &lt;!-- DO NOT EDIT THIS FILE! It was generated automatically. - Edit the source file (news.xml) instead --&gt; - - </xsl:text> - <h1>Releases</h1> - <p>This is the list of official releases for libvirt, along with an - overview of the changes introduced by each of them.</p> - <p>For a more fine-grained view, use the - <a href="https://gitlab.com/libvirt/libvirt/-/commits/master">git log</a>. - </p> - <xsl:apply-templates select="release"/> - <p>Older libvirt releases didn't have proper release notes, - and as such are not included in this page: if you're looking - for information about them, start from those made in - <a href="news-2016.html">2016</a> and work your way back.</p> - </body> - </html> - </xsl:template> - - <!-- Release --> - <xsl:template match="release"> - <h3> - <a> - <xsl:attribute name="id"> - <xsl:value-of select="@version"/> - </xsl:attribute> - <strong> - <xsl:value-of select="@version"/> - <xsl:text> (</xsl:text> - <xsl:value-of select="@date"/> - <xsl:text>)</xsl:text> - </strong> - </a> - </h3> - <ul> - <xsl:apply-templates select="section"/> - </ul> - </xsl:template> - - <!-- Section --> - <xsl:template match="section"> - <li> - <strong> - <xsl:value-of select="@title"/> - </strong> - <xsl:if test="*"> - <ul class="news-section-content"> - <xsl:apply-templates select="change"/> - </ul> - </xsl:if> - </li> - </xsl:template> - - <!-- Change --> - <xsl:template match="change"> - <li> - <dl> - <dt> - <xsl:apply-templates select="summary"/> - </dt> - <dd> - <xsl:apply-templates select="description"/> - </dd> - </dl> - </li> - </xsl:template> - - <!-- Change summary --> - <xsl:template match="summary"> - <xsl:apply-templates/> - </xsl:template> - - <!-- Change description --> - <xsl:template match="description"> - <xsl:apply-templates/> - </xsl:template> - - <!-- <code> HTML tag --> - <xsl:template match="code"> - <xsl:text disable-output-escaping="yes">&lt;code&gt;</xsl:text> - <xsl:apply-templates/> - <xsl:text disable-output-escaping="yes">&lt;/code&gt;</xsl:text> - </xsl:template> - -</xsl:stylesheet> diff --git a/docs/news.rng b/docs/news.rng deleted file mode 100644 index a633e22a7d..0000000000 --- a/docs/news.rng +++ /dev/null @@ -1,72 +0,0 @@ -<?xml version="1.0"?> -<grammar xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> - <start> - <ref name="libvirt"/> - </start> - - <define name="libvirt"> - <element name="libvirt"> - <oneOrMore> - <ref name="release"/> - </oneOrMore> - </element> - </define> - - <define name="release"> - <element name="release"> - <attribute name="version"> - <data type="string"> - <param name="pattern">v[0-9]+\.[0-9]+\.[0-9]+</param> - </data> - </attribute> - <attribute name="date"> - <data type="string"> - <param name="pattern">[0-9]{4}-[0-9]{2}-[0-9]{2}|unreleased</param> - </data> - </attribute> - <oneOrMore> - <ref name="section"/> - </oneOrMore> - </element> - </define> - - <define name="section"> - <element name="section"> - <attribute name="title"> - <data type="string"/> - </attribute> - <zeroOrMore> - <ref name="change"/> - </zeroOrMore> - </element> - </define> - - <define name="change"> - <element name="change"> - <element name="summary"> - <data type="string"> - <!-- Use literal newline instead of \n for bug in libxml2 2.7.6 --> - <param name="pattern">\n[^ -]+\n +</param> - </data> - </element> - <optional> - <element name="description"> - <ref name="description"/> - </element> - </optional> - </element> - </define> - - <define name="description"> - <oneOrMore> - <choice> - <text/> - <element name="code"> - <text/> - </element> - </choice> - </oneOrMore> - </define> - -</grammar> diff --git a/docs/news.xml b/docs/news.xml deleted file mode 100644 index 18d96af048..0000000000 --- a/docs/news.xml +++ /dev/null @@ -1,5473 +0,0 @@ -<?xml version="1.0"?> - -<!-- libvirt release notes - - This file will be processed to produce both HTML and plain text versions - of the release notes. - - Keep the style consistent with existing entries as much as possible. - - Each change should be documented by a short, one-sentence summary, which - should fit in a single line and should not contain any formatting tags. - - You can optionally add a description if you feel like the summary alone is - not enough to document the change accurately. The description may contain - a <code> tag for switching to non-proportional font. No other tags are - allowed. - - Lines should be kept under 80 columns, and should not exceed 100 columns. - - This file is validated against docs/news.rng schema. - - Use the following template to add a new release section: - - <release version="FIXME" date="unreleased"> - <section title="New features"> - </section> - <section title="Improvements"> - </section> - <section title="Bug fixes"> - </section> - </release> - - If relevant for a given release, add a section for these too: - - <section title="Packaging changes"> - </section> - <section title="Removed features"> - </section> - <section title="Security"> - </section> - - --> - -<libvirt> - <release version="v6.5.0" date="unreleased"> - <section title="New features"> - </section> - <section title="Improvements"> - </section> - <section title="Bug fixes"> - </section> - </release> - <release version="v6.4.0" date="2020-06-02"> - <section title="New features"> - <change> - <summary> - qemu: Add support for pvscsi controllers - </summary> - <description> - pvscsi is the VMware paravirtualized SCSI controller, which has been - supported in QEMU for a number of years. - </description> - </change> - <change> - <summary> - cpu: Report model information for ARM CPUs - </summary> - <description> - <code>virsh capabilities</code> will now include information about - the host CPU when run on ARM machines. - </description> - </change> - </section> - <section title="Improvements"> - <change> - <summary> - qemu: stricter validation for disk type='lun' - </summary> - <description> - The 'lun' type is meant for SCSI command passthrough, which can't be - achieved if qemu's block layer features are used. Disk type='lun' is now - allowed only when the format is 'raw' and no other block layer features - are requested. - </description> - </change> - </section> - <section title="Bug fixes"> - <change> - <summary> - qemu: fixed regression in network device hotplug with new qemu versions - </summary> - <description> - Starting from QEMU-5.0 it's required to conform to strict schema when - hotplugging network devices. Libvirt didn't conform to the schema so - in versions prior to 6.4.0 network device hotplug fails in certain - cases. This version fixes it and adds stricter testing to prevent - further issues. - </description> - </change> - <change> - <summary> - remote: Look up libxl driver correctly - </summary> - <description> - This makes <code>xen://</code> connection URIs usable in split daemon - mode. - </description> - </change> - <change> - <summary> - systemd: Start libvirtd after firewalld/iptables services - </summary> - <description> - This solves an issue where iptables rules and chains created by - libvirtd would get removed by a service started after it. - </description> - </change> - <change> - <summary> - network: Re-create iptables chains on firewalld restart - </summary> - <description> - firewalld resets all iptables rules and chains on restart, and this - includes deleting those created by libvirt. - </description> - </change> - </section> - </release> [...] diff --git a/scripts/reformat-news.py b/scripts/reformat-news.py deleted file mode 100755 index d1c3906bd8..0000000000 --- a/scripts/reformat-news.py +++ /dev/null @@ -1,102 +0,0 @@ -#!/usr/bin/env python3 - -# reformat-news.py: Reformat the NEWS file properly -# -# Copyright (C) 2017 Red Hat, Inc. -# -# This library is free software; you can redistribute it and/or -# modify it under the terms of the GNU Lesser General Public -# License as published by the Free Software Foundation; either -# version 2.1 of the License, or (at your option) any later version. -# -# This library is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# Lesser General Public License for more details. -# -# You should have received a copy of the GNU Lesser General Public -# License along with this library. If not, see -# <http://www.gnu.org/licenses/>;. - -import sys - -COLUMNS = 80 - - -def reformat_with_indent(text, initial_indent, indent): - - res = "" - line = initial_indent - - for word in text.split(): - - # If adding one more word (plus a whitespace, plus a newline) - # to the current line would push us over the desired number - # of columns we start a new line instead - if len(line) + len(word) > (COLUMNS - 2): - res = res + line + "\n" - line = indent - - # We need to take care when we've just started a new line, - # as we don't want to add any additional leading whitespace - # in that case - if line == indent or line == initial_indent: - line = line + word - else: - line = line + " " + word - - # Append whatever's left - res = res + line - - return res - - -def reformat(line): - - # Empty lines don't need to be reformatted or even inspected - if len(line) == 0: - return line - - # For all non-empty lines, we decide the indentation level based - # on the first character - marker = line[0] - - # Section - if marker == '*': - initial_indent = 0 - indent = 2 - # Change summary - elif marker == '-': - initial_indent = 2 - indent = 4 - # We use different markers to be able to tell apart the various - # possible indentation levels, but we want to always output the - # same marker in the generated file - line = '*' + line[1:] - # Change description - elif marker == '|': - initial_indent = 4 - indent = 4 - # In this one case, the marker should not ultimately show - # up in the output file, so we strip it before moving on - line = line[1:] - # Anything else should be left as-is - else: - return line - - return reformat_with_indent(line, " " * initial_indent, " " * indent) - - -def main(args): - - if len(args) < 2: - sys.stdout.write("Usage: " + args[0] + " FILE\n") - sys.exit(1) - - with open(args[1], 'r') as f: - for line in f: - print(reformat(line.strip())) - - -if __name__ == "__main__": - main(sys.argv) diff --git a/tests/virschematest.c b/tests/virschematest.c index e4a440afb0..8720031375 100644 --- a/tests/virschematest.c +++ b/tests/virschematest.c @@ -225,8 +225,6 @@ mymain(void) DO_TEST_DIR("storagevol.rng", "storagevolxml2xmlin", "storagevolxml2xmlout", "storagevolschemadata"); - DO_TEST_FILE("../news.rng", "../docs/news.xml"); - return ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE; } -- 2.25.4