docs/go/libvirt.rst | 13 +++++++++++ docs/go/libvirtxml.rst | 10 ++++++++ docs/go/meson.build | 53 ++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 1 + 4 files changed, 77 insertions(+) create mode 100644 docs/go/libvirt.rst create mode 100644 docs/go/libvirtxml.rst create mode 100644 docs/go/meson.build
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.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
The corresponding repos exist
https://gitlab.com/libvirt/libvirt-go-module
https://gitlab.com/libvirt/libvirt-go-xml-module
but I'm leaving them empty until we've completed this release, then
I'll populate with content matching 7.4.0, minus the existing tags.
This change should also wait until after the release.
docs/go/libvirt.rst | 13 +++++++++++
docs/go/libvirtxml.rst | 10 ++++++++
docs/go/meson.build | 53 ++++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 1 +
4 files changed, 77 insertions(+)
create mode 100644 docs/go/libvirt.rst
create mode 100644 docs/go/libvirtxml.rst
create mode 100644 docs/go/meson.build
diff --git a/docs/go/libvirt.rst b/docs/go/libvirt.rst
new file mode 100644
index 0000000000..46250691c1
--- /dev/null
+++ b/docs/go/libvirt.rst
@@ -0,0 +1,13 @@
+=======================
+Libvirt Go Language API
+=======================
+
+The `Go <https://golang.org/>`__ package ``libvirt.org/go/libvirt`` provides
+`CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native Libvirt API.
+
+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
index 0000000000..7583433f56
--- /dev/null
+++ b/docs/go/libvirtxml.rst
@@ -0,0 +1,10 @@
+==========================
+Libvirt Go XML parsing API
+==========================
+
+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.
+
+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
index 0000000000..99fa1b074a
--- /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/meson.build b/docs/meson.build
index f550629d8e..d7afdbd323 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -296,6 +296,7 @@ html_xslt_gen = []
# --- end of XSLT processing ---
subdir('fonts')
+subdir('go')
subdir('html')
subdir('internals')
subdir('js')
--
2.31.1
On Tue, May 25, 2021 at 12:12:08PM +0100, Daniel P. Berrangé wrote: > The corresponding repos exist > > https://gitlab.com/libvirt/libvirt-go-module > https://gitlab.com/libvirt/libvirt-go-xml-module > > but I'm leaving them empty until we've completed this release, then > I'll populate with content matching 7.4.0, minus the existing tags. > This change should also wait until after the release. Thanks for creating the new repos! Please let's make sure all open discussion threads on https://gitlab.com/libvirt/libvirt-go/-/issues/9 are resolved before pushing anything to them. > +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, I believe this should be 'source': 'docs' / 'go' / rst_file, Everything else looks good, but we should also add a note to the existing docs/libvirt-go(-xml).rst telling users that those Go package identifiers are deprecated and they should use the new ones instead. -- Andrea Bolognani / Red Hat / Virtualization
© 2016 - 2024 Red Hat, Inc.