6:02 a.m.
On 11/22/19 3:46 PM, Daniel P. Berrangé wrote:
This refactors existing docs related to the remote driver/daemon and
URIs. It then also adds a kbase page about RPM package options.
This introduces the use of RST for docs as a replacement for HTML.
The intent is that all new docs should use RST from this point.
The POD man pages will also be converted to RST. I'll post this as
a different series.
Note this series only touches the main HTML content, not the
styling / templating using XSL. Tackling that is a separate
job I've not attempted. My guess is that we'd use either Sphinx
or Pelican to do the templating.
Existing HTML docs are candidates for conversion to RST, however,
people should *NOT* attempt todo this manually.
In this series I've converted docs/kbase/ files, using the pandoc
tool. This does a pretty good job in general but does need some
manual cleanups. First I post-processed its output to change the
heading highlighting to follow the documented style
$ cat convert.pl
my @in = <>;
my @out;
for (my $i ; $i <= $#in; $i++) {
my $line = $in[$i];
if ($line =~ /^=+$/) {
my @newout = splice @out, 0, $i - 1;
push @newout, $line;
push @newout, $out[$i-1];
push @newout, $out[$i];
push @newout, $line;
push @newout, "\n";
push @newout, ".. contents::\n";
@out = @newout;
} elsif ($line =~ /^(-|~|^|')+$/) {
$line =~ s/-/=/g;
$line =~ s/~/-/g;
$line =~ s/\^/~/g;
$line =~ s/'/^/g;
push @out, $line;
} else {
push @out, $line;
}
}
print @out;
So I'm converting with
pandoc -f html -t rst < foo.html.in | perl convert.pl > foo.rst
$EDITOR foot.rst
git rm -f foot.html.in
git add foo.rst
After pandoc & the headings convert, there's usually manual fixes
needed to deal with a few oddities pandoc gets wrong, or looks
ugly. This is still way simpler than converting the doc to rst
manually.
Changed in v2:
- Added a style guide for RST docs
- Probe for rst2html's different names
- Added make rules for building rst
- Fixed permalinks in generated docs
- Misc CSS fixes
- Auto-converted all of kbase/ directory
Daniel P. Berrangé (15):
docs: split TLS certificate setup into its own file
docs: move docs about remote driver URIs into URI docs
docs: introduce rst2html as a mandatory tool for building docs
docs: adapt filling of <head> section for rst2html output
docs: generate permalinks correctly for rst2html output
docs: relax CSS context match for pretty tables
docs: add styling for <tt> element
docs: add a minimal style guide for writing RST docs
docs: convert kbase/domainstatecapture.html.in to RST
docs: convert kbase/launch_security_sev.html.in to RST
docs: convert kbase/secureusage.html.in to RST
docs: convert kbase/locking.html.in to RST
docs: convert kbase/locking-lockd.html.in to RST
docs: convert kbase/locking-sanlock.html.in to RST
docs: add a kbase page about RPM packaging options
docs/Makefile.am | 33 +-
docs/aclpolkit.html.in | 20 +-
docs/docs.html.in | 6 +
docs/genaclperms.pl | 2 +-
docs/generic.css | 4 +-
docs/kbase.html.in | 4 +
docs/kbase/domainstatecapture.html.in | 303 -----------
docs/kbase/domainstatecapture.rst | 255 +++++++++
docs/kbase/launch_security_sev.html.in | 533 -------------------
docs/kbase/launch_security_sev.rst | 529 +++++++++++++++++++
docs/kbase/locking-lockd.html.in | 160 ------
docs/kbase/locking-lockd.rst | 121 +++++
docs/kbase/locking-sanlock.html.in | 247 ---------
docs/kbase/locking-sanlock.rst | 193 +++++++
docs/kbase/locking.html.in | 48 --
docs/kbase/locking.rst | 33 ++
docs/kbase/rpm-deployment.rst | 410 +++++++++++++++
docs/kbase/secureusage.html.in | 171 -------
docs/kbase/secureusage.rst | 131 +++++
docs/libvirt.css | 76 +--
docs/migration.html.in | 2 +-
docs/newapi.xsl | 4 +-
docs/page.xsl | 9 +-
docs/remote.html.in | 684 +------------------------
docs/styleguide.rst | 66 +++
docs/tlscerts.html.in | 413 +++++++++++++++
docs/uri.html.in | 263 ++++++++--
libvirt.spec.in | 2 +
m4/virt-external-programs.m4 | 5 +
mingw-libvirt.spec.in | 1 +
30 files changed, 2478 insertions(+), 2250 deletions(-)
delete mode 100644 docs/kbase/domainstatecapture.html.in
create mode 100644 docs/kbase/domainstatecapture.rst
delete mode 100644 docs/kbase/launch_security_sev.html.in
create mode 100644 docs/kbase/launch_security_sev.rst
delete mode 100644 docs/kbase/locking-lockd.html.in
create mode 100644 docs/kbase/locking-lockd.rst
delete mode 100644 docs/kbase/locking-sanlock.html.in
create mode 100644 docs/kbase/locking-sanlock.rst
delete mode 100644 docs/kbase/locking.html.in
create mode 100644 docs/kbase/locking.rst
create mode 100644 docs/kbase/rpm-deployment.rst
delete mode 100644 docs/kbase/secureusage.html.in
create mode 100644 docs/kbase/secureusage.rst
create mode 100644 docs/styleguide.rst
create mode 100644 docs/tlscerts.html.in
Reviewed-by: Michal Privoznik <mprivozn(a)redhat.com>
Michal