From nobody Sat May 4 09:17:31 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1622818045; cv=none; d=zohomail.com; s=zohoarc; b=DHhH7DN5YugTCtSlbufjVntBfdEYIppAL4qrHmVoRfYXrOojxzwGZzrtUn1/z2YBUcDoZEtgWaDCjUIejXYzbx1dhTCcneb24pFL59bm44VjArTdZz3NVUxjcGDSEBeje4XghrlrLWRqeKleD0VzqW94X0oB8MNiOB2sVO9zgh8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1622818045; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=0poHYtFqqCCadoet5H4A9lyZi1RbVAb8P08FrnrvdYE=; b=KTv4gWeCZV7ttGMACxVr8ZM8A5mc18WmdW5v9qteJymB5y5vXL8kZMMKlig0ZI2XE70GpDPQtlOI1x4R77pVraChX53MKc+vPn76XhHttZeVbC9hdJjA7r0UW77SnGUxscjbfEMxVes4HEoZ//HUpXL0LM6qJuZDNkHT0BpVTz4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1622818045229556.2176028464484; Fri, 4 Jun 2021 07:47:25 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-597-yOXL-z4UN66uQ1PMxzDrkg-1; Fri, 04 Jun 2021 10:47:21 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id C7455BBEE6; Fri, 4 Jun 2021 14:47:14 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id EDD6A5D705; Fri, 4 Jun 2021 14:47:11 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id CF71A44A58; Fri, 4 Jun 2021 14:47:07 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 154El6ZA003550 for ; Fri, 4 Jun 2021 10:47:06 -0400 Received: by smtp.corp.redhat.com (Postfix) id 1A5F25E275; Fri, 4 Jun 2021 14:47:06 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-114-239.ams2.redhat.com [10.36.114.239]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4A74C5E26F; Fri, 4 Jun 2021 14:47:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1622818044; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=0poHYtFqqCCadoet5H4A9lyZi1RbVAb8P08FrnrvdYE=; b=HWqz7iFLwb0teDSliLDN3TR+XN1BR+hN6IczG8lCav1WNWTyQ3g2zI/kGFQh/xb2sVJ3tr 4LC81WS1ZsgGmP9fFQWEBzb40Mv7MQShtJkdrprCJwtLVO0GYNr5ktCASqb8Qy/3jm1ys9 StvlF7+GyrXtcmfZTotYEW3d5eb5EKQ= X-MC-Unique: yOXL-z4UN66uQ1PMxzDrkg-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH v2] docs: introduce stubs for new libvirt Go packages Date: Fri, 4 Jun 2021 15:46:59 +0100 Message-Id: <20210604144659.151682-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-loop: libvir-list@redhat.com Cc: Andrea Bolognani X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) 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=C3=A9 --- docs/go/libvirt.rst | 18 ++++++++++++++ docs/go/libvirtxml.rst | 15 ++++++++++++ docs/go/meson.build | 53 +++++++++++++++++++++++++++++++++++++++++ docs/libvirt-go-xml.rst | 12 +++++++--- docs/libvirt-go.rst | 12 +++++++--- docs/meson.build | 1 + 6 files changed, 105 insertions(+), 6 deletions(-) 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..df74660b5f --- /dev/null +++ b/docs/go/libvirt.rst @@ -0,0 +1,18 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Libvirt Go Language API (semver, with Go modules) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The `Go `__ package ``libvirt.org/go/libvirt`` provid= es +`CGo `__ binding from the OS native Libvirt A= PI. + +This package replaces the original `libvirt-go <../libvirt-go.html>`__ +package in order to switch to using `semver `__ and +`Go modules `__. Aside from the changed +import path, the API is fully compatible with the original 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 `__. diff --git a/docs/go/libvirtxml.rst b/docs/go/libvirtxml.rst new file mode 100644 index 0000000000..70b2aca594 --- /dev/null +++ b/docs/go/libvirtxml.rst @@ -0,0 +1,15 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D +Libvirt Go XML parsing API (semver, with Go modules) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + +The `Go `__ package ``libvirt.org/go/libvirtxml`` pro= vides +annotated Go struct definitions for parsing (and formatting) XML documents= used +with libvirt APIs. + +This package replaces the original `libvirt-go-xml <../libvirt-go-xml.html= >`__ +package in order to switch to using `semver `__ and +`Go modules `__. Aside from the changed +import path, the API is fully compatible with the original package. + +For details of Go specific behaviour consult the +`Go package documentation `_= _. diff --git a/docs/go/meson.build b/docs/go/meson.build new file mode 100644 index 0000000000..d2accd322b --- /dev/null +++ b/docs/go/meson.build @@ -0,0 +1,53 @@ +docs_go_files =3D [ + 'libvirt', + 'libvirtxml', +] + +html_xslt_gen_xslt =3D subsite_xsl +html_xslt_gen_install_dir =3D docs_html_dir / 'go' +html_xslt_gen =3D [] + +foreach name : docs_go_files + rst_file =3D '@0@.rst'.format(name) + + html_xslt_gen +=3D { + '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 =3D data['name'] + '.html' + + html_file =3D 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 +=3D html_file + install_web_files +=3D html_file.full_path() + ':' + html_xslt_gen_insta= ll_dir +endforeach + +html_xslt_gen =3D [] + +# --- end of XSLT processing --- diff --git a/docs/libvirt-go-xml.rst b/docs/libvirt-go-xml.rst index 995fdd2b07..11954043c9 100644 --- a/docs/libvirt-go-xml.rst +++ b/docs/libvirt-go-xml.rst @@ -1,10 +1,16 @@ -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D -Libvirt Go XML parsing API -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D +Libvirt Go XML parsing API (calver, no Go modules) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D =20 The `Go `__ package ``libvirt.org/libvirt-go-xml`` pr= ovides annotated Go struct definitions for parsing (and formatting) XML documents= used with libvirt APIs. =20 +This package is replaced by the new `libvirt `__ +package in order to switch to using `semver `__ and +`Go modules `__. Aside from the changed +import path, the new package API is fully compatible with this original +package. + For details of Go specific behaviour consult the `Go package documentation `= __. diff --git a/docs/libvirt-go.rst b/docs/libvirt-go.rst index f2d3f80fb2..7fc1a430a9 100644 --- a/docs/libvirt-go.rst +++ b/docs/libvirt-go.rst @@ -1,10 +1,16 @@ -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -Libvirt Go Language API -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Libvirt Go Language API (calver, no Go modules) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 The `Go `__ package ``libvirt.org/libvirt-go`` provid= es `CGo `__ binding from the OS native Libvirt A= PI. =20 +This package is replaced by the new `libvirt `__ +package in order to switch to using `semver `__ and +`Go modules `__. Aside from the changed +import path, the new package API is fully compatible with this original +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. diff --git a/docs/meson.build b/docs/meson.build index bee0d80d53..4497f7270f 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -297,6 +297,7 @@ html_xslt_gen =3D [] # --- end of XSLT processing --- =20 subdir('fonts') +subdir('go') subdir('html') subdir('internals') subdir('js') --=20 2.31.1