From nobody Fri May 17 05:54:23 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.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 170.10.133.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=1621941151; cv=none; d=zohomail.com; s=zohoarc; b=VDqEPDpczs1gkF84g91+/PgrfaZxgtoYPcb858F0776KQoF0m5fu1eDiTLbfsxtwICD9qhF0Vl+fEr1uiw6E+MfDLpn6v5EtsjpUDB1cT5FEzJ/0za5AKSEZpsnnuGIrYYPALUj6wG/nx47+vzGRl2rFn3rF1Pt/ckZMRAxYFE8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1621941151; h=Content-Type:Content-Transfer-Encoding:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=gpfTzcpKh2+p5B3it4084Ux8UaO8IomJVh7uh+elMYk=; b=hXbNrWgEvCLz1xMbTWHH8ngG5OfaN1ff+bJxPjxJmIMi2J/P/yP+r8keJbaAJFajFsYIg+ThN4PXhkWCP8yTEVa1/a8CEUWshdUVA/g0IsCNLoilDerMHAJDac5iGU9Sktf3lf3oopANtYEBB+jH+7fVZKevTNqB/xWXRfGV+/o= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.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 [170.10.133.124]) by mx.zohomail.com with SMTPS id 1621941151325399.9844270837756; Tue, 25 May 2021 04:12:31 -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-226-Dri0p4VqNrSNiYc2V6H88Q-1; Tue, 25 May 2021 07:12:27 -0400 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id CFC4ABD121; Tue, 25 May 2021 11:12:21 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 00C305D9D3; Tue, 25 May 2021 11:12:18 +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 3359618095C2; Tue, 25 May 2021 11:12:15 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 14PBCEgf006678 for ; Tue, 25 May 2021 07:12:14 -0400 Received: by smtp.corp.redhat.com (Postfix) id 8F4F360CEC; Tue, 25 May 2021 11:12:14 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-114-171.ams2.redhat.com [10.36.114.171]) by smtp.corp.redhat.com (Postfix) with ESMTP id B0DEA60855; Tue, 25 May 2021 11:12:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1621941150; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to: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=gpfTzcpKh2+p5B3it4084Ux8UaO8IomJVh7uh+elMYk=; b=I7m2jPR4SnhwNNRO6nKBKjmx4j1frqmJuzq93KnxCVSj5ncW5KaDP3jd+kWw7QofnAxhZs +wWewkMu+cHPCv0hGyAsnT7k4lE/OXivDuBVUzlNm3r07u6x1vUzlnojgOmFqTLcBGw/yC bEpecnjYrWtI1RcH9EGBcov5CpNKLnc= X-MC-Unique: Dri0p4VqNrSNiYc2V6H88Q-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH] docs: introduce stubs for new libvirt Go packages Date: Tue, 25 May 2021 12:12:08 +0100 Message-Id: <20210525111208.152283-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com 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.14 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 --- 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 @@ +=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 + +The `Go `__ package ``libvirt.org/go/libvirt`` provid= es +`CGo `__ binding from the OS native Libvirt A= PI. + +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..7583433f56 --- /dev/null +++ b/docs/go/libvirtxml.rst @@ -0,0 +1,10 @@ +=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 + +The `Go `__ package ``libvirt.org/go/libvirtxml`` pro= vides +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 `_= _. 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 =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/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 =3D [] # --- end of XSLT processing --- =20 subdir('fonts') +subdir('go') subdir('html') subdir('internals') subdir('js') --=20 2.31.1