[libvirt] [PATCH v2 00/15] docs: some refactoring and new docs about RPM deployment

Fri Nov 22 14:46:47 UTC 2019

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

-- 
2.23.0