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