[libvirt] [PATCH] docs: add pages to support Go module package resolution
Currently the libvirt Go modules are accessed by applications using their github repository URLs. This is undesirable as we don't want applications to have a direct dependancy on a specific source repo location. We want to enable applications to use the Go packages via the libvirt.org namespace. When you do "go get libvirt.org/libvirt-go", the Go client will do an HTTPS request to that URL, and parse the HTML content to look for a <meta> tag which tells it where to the find the GIT repository. https://golang.org/cmd/go/#hdr-Remote_import_paths This adds two pages to support this Go module resolution. They are not linked from anywhere as we don't expect users to actually look at them. If someone does happen upon them, there's some boilerplate text to send them off to godoc.org for API documentation. Since the pages we're adding have a .html extension, we will also use a small apache config tweak on the server RewriteEngine on RewriteRule ^/libvirt-go$ /libvirt-go.html [L] RewriteRule ^/libvirt-go-xml$ /libvirt-go-xml.html [L] Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- docs/libvirt-go-xml.rst | 10 ++++++++++ docs/libvirt-go.rst | 13 +++++++++++++ docs/page.xsl | 6 ++++++ 3 files changed, 29 insertions(+) create mode 100644 docs/libvirt-go-xml.rst create mode 100644 docs/libvirt-go.rst diff --git a/docs/libvirt-go-xml.rst b/docs/libvirt-go-xml.rst new file mode 100644 index 0000000000..ee3b878068 --- /dev/null +++ b/docs/libvirt-go-xml.rst @@ -0,0 +1,10 @@ +========================== +Libvirt Go XML parsing API +========================== + +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. + +For details of Go specific behaviour consult the +`Go package documentation <https://godoc.org/libvirt.org/libvirt-go-xml>`__ diff --git a/docs/libvirt-go.rst b/docs/libvirt-go.rst new file mode 100644 index 0000000000..6ec5c0c123 --- /dev/null +++ b/docs/libvirt-go.rst @@ -0,0 +1,13 @@ +======================= +Libvirt Go Language API +======================= + +The `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go`` 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://godoc.org/libvirt.org/libvirt-go>`__ diff --git a/docs/page.xsl b/docs/page.xsl index f8f7ff8cf9..ddae5ab508 100644 --- a/docs/page.xsl +++ b/docs/page.xsl @@ -99,6 +99,12 @@ <meta name="theme-color" content="#ffffff"/> <title>libvirt: <xsl:value-of select="html:html/html:body//html:h1"/></title> <meta name="description" content="libvirt, virtualization, virtualization API"/> + <xsl:if test="$pagename = 'libvirt-go.html'"> + <meta name="go-import" content="libvirt.org/libvirt-go git https://libvirt.org/git/libvirt-go.git"/> + </xsl:if> + <xsl:if test="$pagename = 'libvirt-go-xml.html'"> + <meta name="go-import" content="libvirt.org/libvirt-go-xml git https://libvirt.org/git/libvirt-go-xml.git"/> + </xsl:if> <xsl:apply-templates select="/html:html/html:head/html:script" mode="content"/> <script type="text/javascript" src="{$href_base}js/main.js"> -- 2.23.0
On Fri, Jan 10, 2020 at 10:03:28 +0000, Daniel P. Berrangé wrote:
Currently the libvirt Go modules are accessed by applications using their github repository URLs. This is undesirable as we don't want applications to have a direct dependancy on a specific source repo location. We want to enable applications to use the Go packages via the libvirt.org namespace.
When you do "go get libvirt.org/libvirt-go", the Go client will do an HTTPS request to that URL, and parse the HTML content to look for a <meta> tag which tells it where to the find the GIT repository.
https://golang.org/cmd/go/#hdr-Remote_import_paths
This adds two pages to support this Go module resolution. They are not linked from anywhere as we don't expect users to actually look at them. If someone does happen upon them, there's some boilerplate text to send them off to godoc.org for API documentation.
Since the pages we're adding have a .html extension, we will also use a small apache config tweak on the server
RewriteEngine on RewriteRule ^/libvirt-go$ /libvirt-go.html [L] RewriteRule ^/libvirt-go-xml$ /libvirt-go-xml.html [L]
Can't we rename the two html file during the build process or add symlinks to them to avoid messing up with apache config? Jirka
On Fri, Jan 10, 2020 at 12:47:51PM +0100, Jiri Denemark wrote:
On Fri, Jan 10, 2020 at 10:03:28 +0000, Daniel P. Berrangé wrote:
Currently the libvirt Go modules are accessed by applications using their github repository URLs. This is undesirable as we don't want applications to have a direct dependancy on a specific source repo location. We want to enable applications to use the Go packages via the libvirt.org namespace.
When you do "go get libvirt.org/libvirt-go", the Go client will do an HTTPS request to that URL, and parse the HTML content to look for a <meta> tag which tells it where to the find the GIT repository.
https://golang.org/cmd/go/#hdr-Remote_import_paths
This adds two pages to support this Go module resolution. They are not linked from anywhere as we don't expect users to actually look at them. If someone does happen upon them, there's some boilerplate text to send them off to godoc.org for API documentation.
Since the pages we're adding have a .html extension, we will also use a small apache config tweak on the server
RewriteEngine on RewriteRule ^/libvirt-go$ /libvirt-go.html [L] RewriteRule ^/libvirt-go-xml$ /libvirt-go-xml.html [L]
Can't we rename the two html file during the build process or add symlinks to them to avoid messing up with apache config?
If we rename them I believe we'll still need apache config to make it serve them with HTML content type since it can't match this from the file extension. I think the rewrite rule is suffiicently simple for our needs. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Fri, Jan 10, 2020 at 11:50:48 +0000, Daniel P. Berrangé wrote:
On Fri, Jan 10, 2020 at 12:47:51PM +0100, Jiri Denemark wrote:
On Fri, Jan 10, 2020 at 10:03:28 +0000, Daniel P. Berrangé wrote:
Currently the libvirt Go modules are accessed by applications using their github repository URLs. This is undesirable as we don't want applications to have a direct dependancy on a specific source repo location. We want to enable applications to use the Go packages via the libvirt.org namespace.
When you do "go get libvirt.org/libvirt-go", the Go client will do an HTTPS request to that URL, and parse the HTML content to look for a <meta> tag which tells it where to the find the GIT repository.
https://golang.org/cmd/go/#hdr-Remote_import_paths
This adds two pages to support this Go module resolution. They are not linked from anywhere as we don't expect users to actually look at them. If someone does happen upon them, there's some boilerplate text to send them off to godoc.org for API documentation.
Since the pages we're adding have a .html extension, we will also use a small apache config tweak on the server
RewriteEngine on RewriteRule ^/libvirt-go$ /libvirt-go.html [L] RewriteRule ^/libvirt-go-xml$ /libvirt-go-xml.html [L]
Can't we rename the two html file during the build process or add symlinks to them to avoid messing up with apache config?
If we rename them I believe we'll still need apache config to make it serve them with HTML content type since it can't match this from the file extension. I think the rewrite rule is suffiicently simple for our needs.
Hmm, you're right. Although the symlink approach should work (according to my testing). The only problem I have with changing the apache config is that it's completely separate from this change and in case we need to modify this in any way, we'd need to remember to update the config too. That said, Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
participants (2)
-
Daniel P. Berrangé -
Jiri Denemark