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

Wed Dec 4 12:02:49 UTC 2019

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 at redhat.com>

Michal