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@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list
