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

[Michal Privoznik]

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)

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

Michal