External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-22 13:45:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

news: Convert to reStructuredText

Browse Source 
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 2020-06-02 13:44:21 +02:00
parent 0ccfcd0361
commit dcd14c88a1
10 changed files with 3374 additions and 5902 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
Makefile.am
View File

@ -46,6 +46,7 @@ EXTRA_DIST = \
README.rst \ README.rst \
AUTHORS.in \ AUTHORS.in \
CONTRIBUTING.rst \ CONTRIBUTING.rst \
NEWS.rst \
scripts/apibuild.py \ scripts/apibuild.py \
scripts/augeas-gentest.py \ scripts/augeas-gentest.py \
build-aux/check-spacing.pl \ build-aux/check-spacing.pl \
@ -68,7 +69,6 @@ EXTRA_DIST = \
scripts/hyperv_wmi_generator.py \ scripts/hyperv_wmi_generator.py \
scripts/mock-noinline.py \ scripts/mock-noinline.py \
scripts/prohibit-duplicate-header.py \ scripts/prohibit-duplicate-header.py \
scripts/reformat-news.py \
scripts/test-wrap-argv.py \ scripts/test-wrap-argv.py \
build-aux/syntax-check.mk \ build-aux/syntax-check.mk \
build-aux/useless-if-before-free \ build-aux/useless-if-before-free \
@ -82,26 +82,6 @@ EXTRA_DIST = \
pkgconfigdir = $(libdir)/pkgconfig pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = libvirt.pc libvirt-qemu.pc libvirt-lxc.pc libvirt-admin.pc 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 rpm: clean
@(unset CDPATH ; $(MAKE) dist && rpmbuild -ta $(distdir).tar.xz) @(unset CDPATH ; $(MAKE) dist && rpmbuild -ta $(distdir).tar.xz)

3362
NEWS.rst Normal file
View File

File diff suppressed because it is too large Load Diff

27
docs/Makefile.am
View File

@ -316,16 +316,18 @@ manpages/virkeyname-%.rst: $(top_srcdir)/src/keycodemapdb/data/keymaps.csv \
manpagesdir = $(HTML_DIR)/manpages manpagesdir = $(HTML_DIR)/manpages
manpages_DATA = $(manpages_html) 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 = \ dot_html_generated_in = \
hvsupport.html.in \ hvsupport.html.in \
news.html.in $(NULL)
dot_html_in = \ dot_html_in = \
$(notdir $(wildcard $(srcdir)/*.html.in)) $(notdir $(wildcard $(srcdir)/*.html.in))
dot_rst = \ dot_rst = \
$(notdir $(wildcard $(srcdir)/*.rst)) $(notdir $(wildcard $(srcdir)/*.rst))
dot_rst_html_in = \ dot_rst_html_in = \
$(dot_rst:%.rst=%.html.in) $(dot_rst:%.rst=%.html.in) \
news.html.in \
$(NULL)
dot_html = \ dot_html = \
$(dot_html_generated_in:%.html.in=%.html) \ $(dot_html_generated_in:%.html.in=%.html) \
$(dot_html_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 \ $(AM_V_GEN)$(RUNUTF8) $(PYTHON) $(top_srcdir)/scripts/hvsupport.py \
$(top_srcdir) $(top_builddir) > $@ || { rm $@ && exit 1; } $(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 %.png: %.fig
convert -rotate 90 $< $@ convert -rotate 90 $< $@
@ -428,6 +417,12 @@ manpages/%.html.in: manpages/%.rst
-e 's|RUNSTATEDIR|$(runstatedir)|g' | \ -e 's|RUNSTATEDIR|$(runstatedir)|g' | \
$(RST2HTML) --strict > $@ || { rm $@ && exit 1; } $(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 %.html.in: %.rst
$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \ $(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
$(RST2HTML) --strict $< > $@ || { rm $@ && exit 1; } $(RST2HTML) --strict $< > $@ || { rm $@ && exit 1; }

15
docs/libvirt.css
View File

@ -560,21 +560,6 @@ td.enumvalue {
color: darkred; 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 { .literal, code {
font-family: monospace; font-family: monospace;
background: #eeeeee; background: #eeeeee;

95
docs/news-ascii.xsl
View File

@ -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>

106
docs/news-html.xsl
View File

@ -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>

72
docs/news.rng
View File

@ -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
View File

File diff suppressed because it is too large Load Diff

102
scripts/reformat-news.py
View File

@ -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)

2
tests/virschematest.c
View File

@ -225,8 +225,6 @@ mymain(void)
DO_TEST_DIR("storagevol.rng", "storagevolxml2xmlin", "storagevolxml2xmlout", DO_TEST_DIR("storagevol.rng", "storagevolxml2xmlin", "storagevolxml2xmlout",
"storagevolschemadata"); "storagevolschemadata");
DO_TEST_FILE("../news.rng", "../docs/news.xml");
return ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE; return ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE;
} }