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

Daniel P. Berrangé posted 15 patches 2 weeks ago
Test syntax-check failed
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/libvirt tags/patchew/20191122144702.3780548-1-berrange@redhat.com
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

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

Posted by Daniel P. Berrangé 2 weeks ago
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

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

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

Posted by Michal Privoznik 4 days ago
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@redhat.com>

Michal

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

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

Posted by Daniel P. Berrangé 4 days ago
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 :|

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list