From 5f3a897b936dc82376ab2b3525020376bb3ff50d Mon Sep 17 00:00:00 2001
From: Peter Krempa <pkrempa@redhat.com>
Date: Tue, 14 Feb 2023 13:51:02 +0100
Subject: [PATCH] docs: Add sub-page for all golang modules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Our documentation has pages for 4 go modules, 2 current and 2 obsolete
ones, but points only to one of them and directly to golang's docs page.

Add a sub-page where all 4 sub-pages for the modules are linked.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
---
 docs/docs.rst    |  2 +-
 docs/golang.rst  | 21 +++++++++++++++++++++
 docs/meson.build |  1 +
 3 files changed, 23 insertions(+), 1 deletion(-)
 create mode 100644 docs/golang.rst

diff --git a/docs/docs.rst b/docs/docs.rst
index a826bd128c..855ce6a069 100644
--- a/docs/docs.rst
+++ b/docs/docs.rst
@@ -79,7 +79,7 @@ Application development
 `Language bindings and API modules <bindings.html>`__
    Bindings of the libvirt API for
    `c# <csharp.html>`__,
-   `go <https://pkg.go.dev/libvirt.org/go/libvirt>`__,
+   `go <https://pkg.go.dev/libvirt.org/go/libvirt>`__ (`all go modules <golang.html>`__),
    `java <java.html>`__,
    `ocaml <https://libvirt.org/ocaml/>`__,
    `perl <https://search.cpan.org/dist/Sys-Virt/>`__,
diff --git a/docs/golang.rst b/docs/golang.rst
new file mode 100644
index 0000000000..ede4d3148e
--- /dev/null
+++ b/docs/golang.rst
@@ -0,0 +1,21 @@
+====================
+Go Language bindings
+====================
+
+Modern libvirt API bindings with Go modules
+-------------------------------------------
+
+The libvirt API bindings package and module for XML manipulation:
+
+ - `libvirt.org/go/libvirt <go/libvirt.html>`__ package https://pkg.go.dev/libvirt.org/go/libvirt
+ - `libvirt.org/go/libvirtxml <go/libvirtxml.html>`__ package https://pkg.go.dev/libvirt.org/go/libvirtxml
+
+
+Obsolete libvirt language bindings
+----------------------------------
+
+The following two go packages were superseded, but software currently using them
+will keep working. No further development will take place.
+
+ - `libvirt.org/libvirt-go <libvirt-go.html>`__ - CGo binding to the native API
+ - `libvirt.org/libvirt-go-xml <libvirt-go-xml.html>`)) - annotated Go struct definitions for XML handling
diff --git a/docs/meson.build b/docs/meson.build
index 5ffd39c01b..a90c59866a 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -80,6 +80,7 @@ docs_rst_files = [
   'formatstorageencryption',
   'glib-adoption',
   'goals',
+  'golang',
   'governance',
   'hacking',
   'hooks',