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

Wed Dec 4 10:45:12 UTC 2019

ping

On Fri, Nov 22, 2019 at 02:46:47PM +0000, 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
> 
> -- 
> 2.23.0
> 

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|