[libvirt] [PATCH v2] docs: attempt to document the general libvirt dev strategy

[Daniel P. Berrangé]

On Mon, Sep 30, 2019 at 03:27:30PM +0200, Michal Privoznik wrote:
> On 9/24/19 5:33 PM, Daniel P. Berrangé wrote:
> > There are various ideas / plans floating around for future libvirt work,
> > some of which is actively in progress. Historically we've never captured
> > this kind of information anywhere, except in mailing list discussions.
> > In particular guidelines in hacking.html.in don't appear until a policy
> > is actively applied.
> > 
> > This patch attempts to fill the documentation gap, by creating a new
> > "strategy" page which outlines the general vision for some notable
> > future changes. The key thing to note is that none of the stuff on this
> > page is guaranteed, plans may change as new information arises. IOW this
> > is a "best guess" as to the desired future.
> > 
> > This doc has focused on three areas, related to the topic of language
> > usage / consolidation
> > 
> >   - Use of non-C languages for the library, daemons or helper tools
> >   - Replacement of autotools with meson
> >   - Use of RST and Sphinx for documentation (website + man pages)
> > 
> > Signed-off-by: Daniel P. Berrangé <berrange at redhat.com>
> > ---
> >   docs/docs.html.in     |   3 +
> >   docs/strategy.html.in | 144 ++++++++++++++++++++++++++++++++++++++++++
> >   2 files changed, 147 insertions(+)
> >   create mode 100644 docs/strategy.html.in
> 
> 
> > +    <p>
> > +      Using the RST format for documentation allows for the use of XSLT to be
> > +      eliminated from the build process. RST and the Sphinx toolkit are widely
> > +      used, as seen by the huge repository of content on
> > +      https://readthedocs.org/. The ability to embed raw HTML in the RST docs
> 
> This could be a clickable URL.
> 
> > +      will greatly facilitate its adoption, avoiding the need for a big bang
> > +      conversion of existing content. Given the desire to eliminate Perl
> > +      usage, replacing the use of POD documentation for manual pages is an
> > +      obvious followup task. RST is the obvious choice to achieve alignment
> > +      with the website, allowing the man pages to be easily published online
> > +      with other docs. It is further anticipated that the current API docs
> > +      generator which uses XSLT to convert the XML API description would be
> > +      converted to something which generates RST using Python instead of XSLT.
> > +    </p>
> > +  </body>
> > +</html>
> > 
> 
> Even though it looks like we are leaning towards Go more than Rust now (at
> least that's my understanding from talking to people face to face), we can
> mention both for now (for instance since you made NSS plugin completely
> unrelated it might be interesting excercise to write it in Rust/Go)

Yeah I think the NSS plugin is something where memory safety would be
especially useful. It is loaded into every process on the host OS and
has some non-trivial parsing code. I'm not convinced that we'd want
to use Go for it though - having a Go runtime in every running process
in the host OS feels undesirable to me.

> Reviewed-by: Michal Privoznik <mprivozn at redhat.com>

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 :|