1. Patchew
  2. Libvirt
  3. View series

[libvirt] [PATCH 0/6] docs: some refactoring and new docs about RPM deployment

Daniel P. Berrangé posted 6 patches 4 years, 5 months ago
Test syntax-check failed
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/libvirt tags/patchew/20191108112112.643266-1-berrange@redhat.com
There is a newer version of this series
.gitignore                    |   1 +
docs/Makefile.am              |  21 +-
docs/daemons.rst              | 209 +++++++++++
docs/docs.html.in             |   6 +
docs/kbase.html.in            |   4 +
docs/kbase/rpm-deployment.rst | 410 ++++++++++++++++++++
docs/page.xsl                 |   4 +-
docs/remote.html.in           | 684 +---------------------------------
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 +
13 files changed, 1309 insertions(+), 714 deletions(-)
create mode 100644 docs/daemons.rst
create mode 100644 docs/kbase/rpm-deployment.rst
create mode 100644 docs/tlscerts.html.in
[libvirt] [PATCH 0/6] docs: some refactoring and new docs about RPM deployment
Posted by Daniel P. Berrangé 4 years, 5 months 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.

Existing HTML docs are candidates for conversion to RST by anyone
interested.

Daniel P. Berrangé (6):
  docs: split TLS certificate setup into its own file
  docs: move docs about remote driver URIs into URI docs
  build: introduce rst2html as a mandatory build tool
  docs: adapt filling of <head> section for rst2html output
  docs: add a kbase page about RPM packaging options
  docs: add page describing the libvirt daemons

 .gitignore                    |   1 +
 docs/Makefile.am              |  21 +-
 docs/daemons.rst              | 209 +++++++++++
 docs/docs.html.in             |   6 +
 docs/kbase.html.in            |   4 +
 docs/kbase/rpm-deployment.rst | 410 ++++++++++++++++++++
 docs/page.xsl                 |   4 +-
 docs/remote.html.in           | 684 +---------------------------------
 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 +
 13 files changed, 1309 insertions(+), 714 deletions(-)
 create mode 100644 docs/daemons.rst
 create mode 100644 docs/kbase/rpm-deployment.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 0/6] docs: some refactoring and new docs about RPM deployment
Posted by Ján Tomko 4 years, 5 months ago 
On Fri, Nov 08, 2019 at 11:21:06AM +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.
>
>Existing HTML docs are candidates for conversion to RST by anyone
>interested.
>

Unlike the Perl -> Python conversion, where we already had a mixture of
both, this actually fulfills the prophecy of XKCD #927 [0]

It would be nice if the first usage of RST actually converted existing
HTML docs, to lead by example, but mostly to demonstrate that it is
reasonably capable of replacing XSLT.

Jano

[0] https://xkcd.com/927/

>Daniel P. Berrangé (6):
>  docs: split TLS certificate setup into its own file
>  docs: move docs about remote driver URIs into URI docs
>  build: introduce rst2html as a mandatory build tool
>  docs: adapt filling of <head> section for rst2html output
>  docs: add a kbase page about RPM packaging options
>  docs: add page describing the libvirt daemons
>
> .gitignore                    |   1 +
> docs/Makefile.am              |  21 +-
> docs/daemons.rst              | 209 +++++++++++
> docs/docs.html.in             |   6 +
> docs/kbase.html.in            |   4 +
> docs/kbase/rpm-deployment.rst | 410 ++++++++++++++++++++
> docs/page.xsl                 |   4 +-
> docs/remote.html.in           | 684 +---------------------------------
> 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 +
> 13 files changed, 1309 insertions(+), 714 deletions(-)
> create mode 100644 docs/daemons.rst
> create mode 100644 docs/kbase/rpm-deployment.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
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH 0/6] docs: some refactoring and new docs about RPM deployment
Posted by Daniel P. Berrangé 4 years, 5 months ago 
On Mon, Nov 11, 2019 at 03:28:28PM +0100, Ján Tomko wrote:
> On Fri, Nov 08, 2019 at 11:21:06AM +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.
> > 
> > Existing HTML docs are candidates for conversion to RST by anyone
> > interested.
> > 
> 
> Unlike the Perl -> Python conversion, where we already had a mixture of
> both, this actually fulfills the prophecy of XKCD #927 [0]
> 
> It would be nice if the first usage of RST actually converted existing
> HTML docs, to lead by example, but mostly to demonstrate that it is
> reasonably capable of replacing XSLT.

I'm happy to convert some existing docs & in fact have already done
some work at converting the .pod man pages to .rst with reasonable
success.

Eliminating POD matches the goals of eliminating perl in general.
Personally I don't mind the POD format in terms of its markup /
complexity, but RST is better known especially in the python world.
So converting the POD to RST addresses XKCD 927.

Converting the main docs/*.html is a fairly large job, that I
was going look at incrementally over a long time. Possibly it
might be possible to use pandoc to autoconvert, as long as the
resulting RST isn't too ugly. TBD.  I don't think this is neccessary
as a blocker for using RST for newly authored docs though.

NB writing content is RST is independent of eliminating XSLT as the
templating system. Elimination oif XSLT depends what templating
system we use, either Sphinx or Pelican - I've not delved into it
to figure out which is better, but I don't see any problem with
either replacing XSLT as it is not as if we do anything especially
clever in XSLT. We're basically just substituting the .html.in files
into a single template and generating a table of contents.

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
Re: [libvirt] [PATCH 0/6] docs: some refactoring and new docs about RPM deployment
Posted by Kashyap Chamarthy 4 years, 5 months ago 
On Mon, Nov 11, 2019 at 02:39:35PM +0000, Daniel P. Berrangé wrote:

[...]

 
> NB writing content is RST is independent of eliminating XSLT as the
> templating system. Elimination oif XSLT depends what templating
> system we use, either Sphinx or Pelican - I've not delved into it
> to figure out which is better,

FWIW, Sphinx seems to be the "preferred" choice for Linux[*], QEMU.
(OpenStack upstream also uses it heavily.)

[...]

[*] https://www.kernel.org/doc/html/v4.11/doc-guide/sphinx.html


-- 
/kashyap

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH 0/6] docs: some refactoring and new docs about RPM deployment
Posted by Daniel P. Berrangé 4 years, 5 months ago 
On Wed, Nov 13, 2019 at 02:53:21PM +0100, Kashyap Chamarthy wrote:
> On Mon, Nov 11, 2019 at 02:39:35PM +0000, Daniel P. Berrangé wrote:
> 
> [...]
> 
>  
> > NB writing content is RST is independent of eliminating XSLT as the
> > templating system. Elimination oif XSLT depends what templating
> > system we use, either Sphinx or Pelican - I've not delved into it
> > to figure out which is better,
> 
> FWIW, Sphinx seems to be the "preferred" choice for Linux[*], QEMU.
> (OpenStack upstream also uses it heavily.)

Yep, but there's a difference for libvirt's needs. IIUC those projects are
all building the docs into a manual. Libvirt is building its docs into a
website with a series of pages. I've not investigated in a lot of detail,
but my first impressions are that Pelican is better suited for building
websites, while Sphinx is better suited for building manuals. Both use
RST as their input though, so the decision of which to use mostly impacts
the way we later replace the XSLT with a new page template, so I've not
spent much time on it yet.


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

Patchew 2.1-devel-0870f84

© 2016 - 2024 Red Hat, Inc.