mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 13:45:38 +00:00
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@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com>
This commit is contained in:
Andrea Bolognani
parent
0ccfcd0361
commit
dcd14c88a1
22
Makefile.am
22
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 \
|
||||
@ -68,7 +69,6 @@ EXTRA_DIST = \
|
||||
scripts/hyperv_wmi_generator.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 \
|
||||
@ -82,26 +82,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)
|
||||
|
||||
|
||||
@ -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; }
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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>
|
||||
@ -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"><!DOCTYPE html>
|
||||
</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">
|
||||
|
||||
<!-- DO NOT EDIT THIS FILE! It was generated automatically.
|
||||
Edit the source file (news.xml) instead -->
|
||||
|
||||
</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"><code></xsl:text>
|
||||
<xsl:apply-templates/>
|
||||
<xsl:text disable-output-escaping="yes"></code></xsl:text>
|
||||
</xsl:template>
|
||||
|
||||
</xsl:stylesheet>
|
||||
@ -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>
|
||||
5473
docs/news.xml
5473
docs/news.xml
File diff suppressed because it is too large
Load Diff
@ -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)
|
||||
@ -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;
|
||||
}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user