Instead of storing release notes as XML and then converting them
to HTML and ASCII at build time using XSLT and a custom script,
we can use reStructuredText as both the source and ASCII
representation and generate HTML from it using the same tooling
we already use for the rest of the documentation.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
As the name clearly implies, it's supposed to list the .html.in
files that are generated from .rst files, but it mistakenly lists
the corresponding .html files instead.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The use of 32favicon.png was removed when the new favicons were
introduced in
commit 40cb5581c4
Author: Daniel P. Berrangé <berrange@redhat.com>
Date: Wed Jul 26 18:22:11 2017 +0100
docs: add full set of "favicon" files to support modern clients
Reviewed-by: Laine Stump <laine@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The various favicon files were missing from the favicon list, so never
installed, as was an example code diagram.
Reviewed-by: Laine Stump <laine@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
We previously added a hack to symlink CSS files from the source dir into
the build dir, to allow the website to be browsed locally. We should
have also done this for any images.
This change merges several variables into one "$(assets)" so that we
treat all static files in the root dir the same way.
Reviewed-by: Laine Stump <laine@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
We've adopted reStructuredText as the primary markup language for
our documentation and, given that both GitLab and GitHub can render
documents in this format just fine, it makes sense to get rid of
the few last remaining bits of Markdown and standardize on
reStructuredText across the board.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
To encourage contributors to make changes to the main website, add a
footer link to every page which links to the corresponding source file
in git. With gitlab, they are able to edit content directly in the web
browser and then submit a merge request. This gives a way to contribute
content that is arguably easier than our wiki which requires manual
account creation, while this will also benefit from maintainer review.
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The --strict arg forces the rst tools to abort with an error instead
of printing warnings to stderr, or the output document.
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The previous "QEMU shim" proof of concept was taking an approach of only
caring about initial spawning of the QEMU process. It was then
registered with the libvirtd daemon who took over management of it. The
intent was that later libvirtd would be refactored so that the shim
retained control over the QEMU monitor and libvirt just forwarded APIs
to each shim as needed. This forwarding of APIs would require quite alot
of significant refactoring of libvirtd to achieve.
This impl thus takes a quite different approach, explicitly deciding to
keep the VMs completely separate from those seen & managed by libvirtd.
Instead it uses the new "qemu:///embed" URI scheme to embed the entire
QEMU driver in the shim, running with a custom root directory.
Once the driver is initialization, the shim starts a VM and then waits
to shutdown automatically when QEMU shuts down, or should kill QEMU if
it is terminated itself. This ought to use the AUTO_DESTROY feature but
that is not yet available in embedded mode, so we rely on installing a
few signal handlers to gracefully kill QEMU. This isn't reliable if
we crash of course, but you can restart with the same root dir.
Note this program does not expose any way to manage the QEMU process,
since there's no RPC interface enabled. It merely starts the VM and
cleans up when the guest shuts down at the end. This program is
installed to /usr/bin/virt-qemu-run enabling direct use by end users.
Most use cases will probably want to integrate the concept directly
into their respective application codebases. This standalone binary
serves as a nice demo though, and also provides a way to measure
performance of the startup process quite simply.
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
As part of a goal to eliminate Perl from libvirt build tools,
rewrite the genaclperms.pl tool in Python.
This was a straight conversion, manually going line-by-line to
change the syntax from Perl to Python. Thus the overall structure
of the file and approach is the same.
Tested-by: Cole Robinson <crobinso@redhat.com>
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
As part of a goal to eliminate Perl from libvirt build tools,
rewrite the hvsupport.pl tool in Python.
This was a straight conversion, manually going line-by-line to
change the syntax from Perl to Python. Thus the overall structure
of the file and approach is the same.
The new impl generates byte-for-byte identical output to the
old impl.
Tested-by: Cole Robinson <crobinso@redhat.com>
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The keycodemap tool is told to generate docs in rst format now
instead of pod.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The rst2man tool is provided by python docutils, and as the name
suggests, it converts RST documents into man pages.
The intention is that our current POD docs will be converted to
RST format, allowing one more use of Perl to be eliminated from
libvirt.
The manual pages will now all be kept in the docs/manpages/ directory,
which enables us to include the man pages in the published website.
This is good for people searching for libvirt man pages online as it
makes it more likely google will send them to the libvirt.org instead
of some random third party man page site with outdated content.
Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The rst2html tool is provided by python docutils, and as the name
suggests, it converts RST documents into HTML.
Basic rules are added for integrating RST docs into the website
build process.
This enables us to start writing docs on our website in RST format
instead of HTML, without changing the rest of our website templating
system away from XSLT yet.
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
After generating the API HTML files we run xmllint in docs/html/*.html
to validate the correctness. Since
commit 0aa8536f14
Author: Daniel P. Berrangé <berrange@redhat.com>
Date: Wed Nov 20 14:49:26 2019 +0000
docs: generate API reference pages for admin, qemu & lxc libraries
we have many rules generating files into docs/html/. The xmllint
calls for each rule are picking up files which are part-generated by
other parallel build rules resulting in transient errors like:
GEN html/index.html
GEN html/index-admin.html
GEN html/index-qemu.html
GEN html/index-lxc.html
GEN hvsupport.html.in
html/index-lxc.html:1: parser error : Document is empty
^
make[4]: *** [Makefile:2407: html/index-qemu.html] Error 1
The easiest solution is to move the xmllint rules to the 'make check'
phase of the build.
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The XSL generator loads included HTML files relative to the source dir
but we need to tell it to load them from the build dir instead.
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Some of the web content is only present in the source tree, thus when
viewing pages from the build tree they appear missing.
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The API cross reference files are not used since
commit d3043afe5c
Author: Daniel Veillard <veillard@redhat.com>
Date: Mon Jan 21 08:08:33 2008 +0000
Remove docs/API*.html
* docs/API* docs/api.xsl docs/site.xsl docs/Makefile.am: remove the
generation of the API*.html files as it's not really useful here
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Define automake variables for all the data we need built and installed
and let automake generate the install rules normally.
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Historically we did not support VPATH builds and everything was
generated into source directory. The introduction of VPATH builds did
not changed the way how our documentation is handled.
This patch changes the rules to generate everything into build
directory and stops distributing generated files in order to have
properly separated VPATH builds.
Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
There is no need to have the libvirt-admin.so library definition in the
src directory. In addition the library uses directly code from admin
sub-directory so move the remaining bits there as well.
Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Some of the typed parameter APIs are exported publicly, but the
implementation was intermixed with private functions. Introduce
virtypedparam-public.c, move all public API functions there and purge
the comments stating that some functions are public.
This will decrease the likelihood of messing up the expectations as well
as it will become more clear which of them are actually public.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Python3 versions less than 3.7 have very unhelpful handling
of the C locale where they assume data is 7-bit only. This
violates POSIX which requires the C locale to be 8-bit clean.
Python3 >= 3.7 now assumes that the C locale is always UTF-8.
Set env variables to force LC_CTYPE to en_US.UTF-8 so that
we get UTF-8 handling on all python versions. Note we do
not use C.UTF-8 since not all C libraries support that.
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
We currently generate two completely separate API references for the
libvirt public API. One at 'docs/html/' and one at 'docs/devhelp/'.
Both are published on the website, but we only link to content in
the 'docs/html/' pages.
Both are installed in the libvirt-docs sub-RPM, with a full copy
of the website including 'docs/html/' in /usr/share/docs/libvirt-docs,
while the 'docs/devhelp/' content goes to /usr/share/gtk-doc/. The
latter was broken for years until:
commit ca6f602546
Author: Andrea Bolognani <abologna@redhat.com>
Date: Fri May 10 14:54:52 2019 +0200
docs: Introduce $(devhelphtml_generated)
Our XSLT magic generates one Devhelp-compatible HTML file
per documentation module, but so far we have only shipped
and installed documentation for virterror.
Now that we have $(modules), however, we can generate the
list of files the same way we do for regular documentation
and make sure we always ship and install everything.
That this bug went unnoticed for so long is a sign of how few
people are using the devhelp docs. The only commits to the devhelp
code since it was first introduced have been fixing various build
problems that hit.
The only obvious difference between the two sets of docs is the CSS
styling in use. Overall devhelp does not look compelling enough to
justify having two duplicated sets of API docs. Eliminating it will
reduce the amount of XSL code we are carrying in the tree which is
an attractive benefit.
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Introduce a bunch of new public APIs related to backup checkpoints.
Checkpoints are modeled heavily after virDomainSnapshotPtr (both
represent a point in time of the guest), although a snapshot exists
with the intent of rolling back to that state, while a checkpoint
exists to make it possible to create an incremental backup at a later
time. We may have a future hypervisor that can completely manage
checkpoints without libvirt metadata, but the first two planned
hypervisors (qemu and test) both always use libvirt for tracking
metadata relations between checkpoints, so for now, I've deferred
the counterpart of virDomainSnapshotHasMetadata for a separate
API addition at a later date if there is ever a need for it.
Note that until we allow snapshots and checkpoints to exist
simultaneously on the same domain (although the actual prevention of
this will be in a separate patch for the sake of an easier revert down
the road), that it is not possible to branch out to create more than
one checkpoint child to a given parent, although it may become
possible later when we revert to a snapshot that coincides with a
checkpoint. This also means that for now, the decision of which
checkpoint becomes the parent of a newly created one is the only
checkpoint with no child (so while there are APIs for dealing with a
current snapshot, we do not need those for checkpoints). We may end
up exposing a notion of a current checkpoint later, but it's easier to
add stuff when proven needed than to blindly support it now and wish
we hadn't exposed it.
The following map shows the API relations to snapshots, with new APIs
on the right:
Operate on a domain object to create/redefine a child:
virDomainSnapshotCreateXML virDomainCheckpointCreateXML
Operate on a child object for lifetime management:
virDomainSnapshotDelete virDomainCheckpointDelete
virDomainSnapshotFree virDomainCheckpointFree
virDomainSnapshotRef virDomainCheckpointRef
Operate on a child object to learn more about it:
virDomainSnapshotGetXMLDesc virDomainCheckpointGetXMLDesc
virDomainSnapshotGetConnect virDomainCheckpointGetConnect
virDomainSnapshotGetDomain virDomainCheckpointGetDomain
virDomainSnapshotGetName virDomainCheckpiontGetName
virDomainSnapshotGetParent virDomainCheckpiontGetParent
virDomainSnapshotHasMetadata (deferred for later)
virDomainSnapshotIsCurrent (no counterpart, see note above)
Operate on a domain object to list all children:
virDomainSnapshotNum (no counterparts, these are the old
virDomainSnapshotListNames racy interfaces)
virDomainSnapshotListAllSnapshots virDomainListAllCheckpoints
Operate on a child object to list descendents:
virDomainSnapshotNumChildren (no counterparts, these are the old
virDomainSnapshotListChildrenNames racy interfaces)
virDomainSnapshotListAllChildren virDomainCheckpointListAllChildren
Operate on a domain to locate a particular child:
virDomainSnapshotLookupByName virDomainCheckpointLookupByName
virDomainSnapshotCurrent (no counterpart, see note above)
virDomainHasCurrentSnapshot (no counterpart, old racy interface)
Operate on a snapshot to roll back to earlier state:
virDomainSnapshotRevert (no counterpart, instead checkpoints
are used in incremental backups via
XML to virDomainBackupBegin)
Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Set a default namespace in the stylesheet instead.
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Acked-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
The previously added AMD SEV doc was not linked from anywhere on the
website. Address this by introducing a new "Knowledge base" section
that can hold task oriented guide to various features. Moving the SEV,
disk locking and secure usage guides under this section.
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
At the moment we allow the user to specify exactly where
they want the HTML documentation to be installed with an
extreme level of precision through the --with-html-dir and
--with-html-subdir configure options.
Most of the time, of course, the user will stick with the
default, that is $(datadir)/doc/$(PACKAGE)-$(VERSION)/html.
So close to $(docdir)! Including the version number in
the path, specifically, seems entirely unnecessary since
different releases of libvirt are not going to be able to
coexist on the same system anyway.
Drop all these custom flexibilty for flexibilty's sake
shenaningans in favor of the standard, well understood
$(docdir).
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Acked-by: Michal Privoznik <mprivozn@redhat.com>
Our XSLT magic generates one Devhelp-compatible HTML file
per documentation module, but so far we have only shipped
and installed documentation for virterror.
Now that we have $(modules), however, we can generate the
list of files the same way we do for regular documentation
and make sure we always ship and install everything.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Acked-by: Michal Privoznik <mprivozn@redhat.com>
This variable contains a lists of documentation modules,
in a neutral format.
Right now is only used to define $(apihtml_generated), but
later on we're gonna reuse it.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Acked-by: Michal Privoznik <mprivozn@redhat.com>
Instead of duplicating javascript in every single page, put it in a
standalone file which can be cached by the browser.
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Andrea Bolognani