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>
libvirt.org/search.php drops into some kind of screen which I guess
is supposed to show a search bar with options, but presently for me
renders as nothing but the following text:
Search the documentation on Libvirt.org
The search service indexes the libvirt APIs and documentation as well as the libvir-list@redhat.com mailing-list archives. To use it simply provide a set of keywords:
The main page search bar now redirects to google, this page is broken,
I say we just remove it and move on.
Reviewed-by: Daniel P. Berrange <berrange@redhat.com>
Signed-off-by: Cole Robinson <crobinso@redhat.com>
Right-aligning backslashes when defining macros or using complex
commands in Makefiles looks cute, but as soon as any changes is
required to the code you end up with either distractingly broken
alignment or unnecessarily big diffs where most of the changes
are just pushing all backslashes a few characters to one side.
Generated using
$ git grep -El '[[:blank:]][[:blank:]]\\$' | \
grep -E '*\.([chx]|am|mk)$$' | \
while read f; do \
sed -Ei 's/[[:blank:]]*[[:blank:]]\\$/ \\/g' "$f"; \
done
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
The website does not look good in a mobile device as the text is
far too small and the layout assumes a wide screen.
Make the style dynamically adapt based on viewport size, so a
mobile device gets a layout more suited to its dimensions,
also changing "Learn" to "Docs"
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Commit id '94d2d6429' caused a syntax-error check to fail:
docs/Makefile.am:276: $(AM_V_GEN)sed -e '/<span id="php_placeholder"><\/span>/r '"$(srcdir)/$@.code.in" \
maint.mk: Wrap long lines in Makefiles
cfg.mk:721: recipe for target 'sc_prohibit_long_lines' failed
make: *** [sc_prohibit_long_lines] Error 1
make: *** Waiting for unfinished jobs....
Altered the line to put another line wrap between sed and -e
We already require libxml to be installed, so it is not unreasonable
to require xmllint and xsltproc to be installed too - any platform
with the former will have the latter too.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
The HTML pages are currently validated against an XHTML 1.0 DTD.
This makes it impossible to take advantage of features that are
introduced in HTML 5, because they'll fail validation.
There is intentionally no DTD defined for HTML 5, so there's no
alternative to XHTML 1.0 DTD that we could switch to. The only
options are to stick with XHTML 1.0 forever, or drop the DTD
validation, and we pick the latter.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
In order not to make the build even less reproducible, honour
SOURCE_DATE_EPOCH environment variable as specified:
https://reproducible-builds.org/specs/source-date-epoch/
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Despite being a generated file, HACKING has been tracked in
the git repository along with actual source files. As far as
I'm aware, it's the only generated file for which that happens.
Times and times again, people[1] have committed changes to
the source file without refreshing the generated copy at the
same time.
The rationale for tracking the generated file is to help out
people who just cloned the git repository looking to contribue;
however, README-hacking already contains enough information to
get perspective contributors to a place where they can simply
look at docs/hacking.html instead.
[1] Mostly me, to be honest
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Currently, building the NEWS file involves using a XSLT stylesheet
to extract information from the same HTML file that's used on the
libvirt website.
The process works, but it's quite fiddly in that it requires the
source HTML to be formatted in a very precise way, and a single
missing newline can mess up the resulting plain text considerably.
Moreover, the XSLT stylesheet itself encodes a lot of the details
of converting to plain text in a way that's not necessarily easy
to understand, tweak or fix.
To improve the process, move all existing entries to a new XML
file that contains exactly the information we care about in a
simple structured format, and start generating both the HTML and
plain text versions of the release notes using XSLT stylesheets
that can now afford to be almost trivial.
When changing one of the src/libvirt-*.c files to alter the docs, the
adjusted files weren't being built. Added them into APIBUILD_STAMP and
then added that to the html/index.html rule which is used for the
$(apihtml_generated) generated rule.
Also, for clean we can remove the html/*.html files
Remove a bunch of pages which are either outdated, have no
content, or duplicate content better described elsewhere
in the site or wiki.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
A combination of the index page, top nav bar and docs.html page
provide links to all pages on the site. The left hand nav bar
is thus redundant and can be removed to provide a simpler style
for the site.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Replace the old "Made with libvirt" logo with links to the
new "Libvirt powered" logos, providing various sizes.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Use a dark banner whose color matches the dark green used in
the logo. Introduce a newly rendered version of the header
logo derived from new SVG file, instead of old one from
(now lost) Adobe Illustrator file.
The top banner logo now links to the front page as is common
practice for most websites.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Add the SVG files for the libvirt logo, along with corresponding
pre-rendered PNG bitmaps at key sizes. Also add a README file
describing how to modify the logos and their intended usages.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
So, I've ran into very interesting problem lately. When doing the
following, I've encountered an error:
libvirt.git $ make dist && tar -xJf libvirt-2.2.0.tar.xz && \
cd libvirt-2.2.0 && ./configure && \
rm docs/formatdomain.html && make -C docs
make: Entering directory 'docs'
make: *** No rule to make target 'formatdomain.html', needed by 'web'. Stop.
make: Leaving directory 'docs'
I had no idea what was going on, so I've nailed down the commit
that "broke it" via running git-bisect. It was this one:
7659bd9221. But that shed no more light until I realized
that the commit might actually just exposed a problem we had. And
guess what - I've nailed it down. Of course we are not
distributing subsite.xsl that's why make prints error message.
Very misleading one I must say.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
