docs: introduce stubs for new libvirt Go packages

Currently we expose libvirt Go packages at

  libvirt.org/libvirt-go
  libvirt.org/libvirt-go-xml

These packages have not supported Go modules historically and when we
tried to introduce modules, we hit the problem that we're not using
semver for versioning.

The only way around this is to introduce new packages under a different
namespace, that will have the exact same code, but be tagged with a
different version numbering scheme.

This change proposes:

  libvirt.org/go/libvirt
  libvirt.org/go/libvirtxml

Note the hyphen is removed so that the import basename matches the
Go package name.

Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

diff --git a/docs/go/libvirt.rst b/docs/go/libvirt.rst
new file mode 100644 (file)
index 0000000..6a1344a
--- /dev/null
+++ b/docs/go/libvirt.rst
@@ -0,0 +1,19 @@
+=========================================
+Libvirt Go Language API (with Go modules)
+=========================================
+
+The `Go <https://golang.org/>`__ package ``libvirt.org/go/libvirt`` provides
+`CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native Libvirt API.
+
+This package replaces the obsolete `libvirt.org/libvirt-go
+<../libvirt-go.html>`__ package in order to switch to using `semver
+<https://semver.org/>`__ and `Go modules <https://golang.org/ref/mod>`__.
+Aside from the changed import path and versioning scheme, the API is fully
+compatible with the legacy package.
+
+In general the Go representation is a direct 1-1 mapping from native API
+concepts to Go, so the native API documentation should serve as a reference
+for most behaviour.
+
+For details of Go specific behaviour consult the
+`Go package documentation <https://pkg.go.dev/libvirt.org/go/libvirt>`__.

diff --git a/docs/go/libvirtxml.rst b/docs/go/libvirtxml.rst
new file mode 100644 (file)
index 0000000..5407d60
--- /dev/null
+++ b/docs/go/libvirtxml.rst
@@ -0,0 +1,16 @@
+============================================
+Libvirt Go XML parsing API (with Go modules)
+============================================
+
+The `Go <https://golang.org/>`__ package ``libvirt.org/go/libvirtxml`` provides
+annotated Go struct definitions for parsing (and formatting) XML documents used
+with libvirt APIs.
+
+This package replaces the obsolete `libvirt.org/libvirt-go-xml
+<../libvirt-go-xml.html>`__ package in order to switch to using `semver
+<https://semver.org/>`__ and `Go modules <https://golang.org/ref/mod>`__.
+Aside from the changed import path and versioning scheme, the API is fully
+compatible with the original package.
+
+For details of Go specific behaviour consult the
+`Go package documentation <https://pkg.go.dev/libvirt.org/go/libvirtxml>`__.

diff --git a/docs/go/meson.build b/docs/go/meson.build
new file mode 100644 (file)
index 0000000..d2accd3
--- /dev/null
+++ b/docs/go/meson.build
@@ -0,0 +1,53 @@
+docs_go_files = [
+  'libvirt',
+  'libvirtxml',
+]
+
+html_xslt_gen_xslt = subsite_xsl
+html_xslt_gen_install_dir = docs_html_dir / 'go'
+html_xslt_gen = []
+
+foreach name : docs_go_files
+  rst_file = '@0@.rst'.format(name)
+
+  html_xslt_gen += {
+    'name': name,
+    'file': docs_rst2html_gen.process(rst_file),
+    'source': 'docs' / 'go' / rst_file,
+  }
+endforeach
+
+# keep the XSLT processing code block in sync with docs/meson.build
+
+# --- begin of XSLT processing ---
+
+foreach data : html_xslt_gen
+  html_filename = data['name'] + '.html'
+
+  html_file = custom_target(
+    html_filename,
+    input: data.get('file', data['name'] + '.html.in'),
+    output: html_filename,
+    command: [
+      xsltproc_prog,
+      '--stringparam', 'pagesrc', data.get('source', ''),
+      '--stringparam', 'builddir', meson.build_root(),
+      '--stringparam', 'timestamp', docs_timestamp,
+      '--nonet',
+      html_xslt_gen_xslt,
+      '@INPUT@',
+    ],
+    depends: data.get('depends', []),
+    depend_files: [ page_xsl ],
+    capture: true,
+    install: true,
+    install_dir: html_xslt_gen_install_dir,
+  )
+
+  install_web_deps += html_file
+  install_web_files += html_file.full_path() + ':' + html_xslt_gen_install_dir
+endforeach
+
+html_xslt_gen = []
+
+# --- end of XSLT processing ---

diff --git a/docs/libvirt-go-xml.rst b/docs/libvirt-go-xml.rst
index 995fdd2b07a9c80164264b541997dfc129f28888..d2a488d99d639452085e9a5c1c761a6de092cffe 100644 (file)
--- a/docs/libvirt-go-xml.rst
+++ b/docs/libvirt-go-xml.rst
@@ -1,10 +1,22 @@
-==========================
-Libvirt Go XML parsing API
-==========================
+===================================================
+Obsolete libvirt Go XML parsing API (no Go modules)
+===================================================
 
-The `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go-xml`` provides
-annotated Go struct definitions for parsing (and formatting) XML documents used
-with libvirt APIs.
+The obsolete `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go-xml``
+provided annotated Go struct definitions for parsing (and formatting) XML
+documents used with libvirt APIs.
+
+This package is replaced by the new `libvirt.org/go/libvirtxml
+<go/libvirtxml.html>`__ package in order to switch to using `semver
+<https://semver.org/>`__ and `Go modules <https://golang.org/ref/mod>`__.
+Aside from the changed import path and versioning scheme, the new package API
+is fully compatible with this legacy package.
+
+Software currently using this package will keep working, but no further
+development will take place. libvirt XML scheme elements/attributes introduced
+after 7.4.0 will never be available. Authors are strongly recommended to switch
+imports to point to the new package, to prepare for future Go toolchains
+which will mandate Go module support and semver.
 
 For details of Go specific behaviour consult the
 `Go package documentation <https://pkg.go.dev/libvirt.org/libvirt-go-xml>`__.

diff --git a/docs/libvirt-go.rst b/docs/libvirt-go.rst
index f2d3f80fb24a7c7a1fa0f0eafa93f83ad6323a70..85ee3191b5bb4fa5a62b9cc32886ce8f84a3965c 100644 (file)
--- a/docs/libvirt-go.rst
+++ b/docs/libvirt-go.rst
@@ -1,9 +1,22 @@
-=======================
-Libvirt Go Language API
-=======================
+================================================
+Obsolete libvirt Go Language API (no Go modules)
+================================================
 
-The `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go`` provides
-`CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native Libvirt API.
+The obsolete `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go``
+provided `CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native
+Libvirt API.
+
+This package is replaced by the new `libvirt.org/go/libvirt <go/libvirt.html>`__
+package in order to switch to using `semver <https://semver.org/>`__ and
+`Go modules <https://golang.org/ref/mod>`__. Aside from the changed
+import path and versioning scheme, the new package API is fully compatible
+with this legacy package.
+
+Software currently using this package will keep working, but no further
+development will take place. libvirt APIs/constants introduced after
+7.4.0 will never be available. Authors are strongly recommended to switch
+imports to point to the new package, to prepare for future Go toolchains
+which will mandate Go module support and semver.
 
 In general the Go representation is a direct 1-1 mapping from native API
 concepts to Go, so the native API documentation should serve as a reference

diff --git a/docs/meson.build b/docs/meson.build
index bee0d80d538a3ae5cb2c8d1af67840f351bd8278..4497f7270f9e16685fc3b0f5329816e3ec240705 100644 (file)
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -297,6 +297,7 @@ html_xslt_gen = []
 # --- end of XSLT processing ---
 
 subdir('fonts')
+subdir('go')
 subdir('html')
 subdir('internals')
 subdir('js')