Re: [libvirt] [PATCH 0/6] docs: some refactoring and new docs about RPM deployment
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 :|