1
0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-22 17:34:18 +03:00
Commit Graph

55 Commits

Author SHA1 Message Date
Peter Krempa
c472736062 docs: newapi: Fix generation of type definition tables
Ensure that all rows have 3 columns and avoid generation of emtpy
elements which would be turned by the XML formatter into non-pair td/tr
tags which don't work properly with HTML5 parsers.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2024-03-01 12:51:56 +01:00
Peter Krempa
620cbfaea5 docs: newapi: Properly skip ACL entries if empty
The source document can contain an empty '@flags' attribute which passes
the test but generates an empty element. Check that flags is non-empty
to trigger the fallback.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2024-03-01 12:51:56 +01:00
Peter Krempa
6f4485a453 docs: newapi: Avoid table where every row has an cell with 'colspan'
The HTML standard requires that a table column must include at least one
row which defines it exclusively, thus having a table where all rows
unite it via 'colspan' is illegal.

Modify the enum value generator to always output the description field
even when it's empty rather than uniting it, as in case when each value
doesn't have a description the generated document would violate the
standard.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2024-03-01 12:51:56 +01:00
Peter Krempa
47a8ff9979 docs: newapi: Avoid empty <div>s when there is no description
The various objects we generate API for may have empty description in
which case an empty div would be generated when processing the API
description. As we're using XML output mode the generator would shorten
such divs to the non-pair empty element version, which doesn't work well
with HTML5 parsers requiring a pair tag for <div>

Avoid empty description <div> elements altogether by skipping it if the
description is empty.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2024-03-01 12:51:56 +01:00
Peter Krempa
3a0af92df6 docs: newapi: Don't generate empty <div> in template for ACL permissions
If an API has no ACLs an empty <div class='acl'/> would be generated
which is mis-interpreted by browsers when creating DOM to nest any
subsequent elements under it.

Don't generate the ACL section div unless it will be filled.

Best viewed with 'git show -w'

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2024-03-01 12:51:56 +01:00
Peter Krempa
e49b305c56 docs: site: Don't generate '<?xml' header for HTML documents
Skip the XML header as it's invalid with <!DOCTYPE HTML> both for the
RST-generated pages and for the API docs generated from the API XML.

Additionally remove the spurious xsl:output directive from newapi.xsl
which is ignored and thus misleading.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2024-03-01 12:51:55 +01:00
Peter Krempa
c4e35af08c docs: page.xsl: Split up 'href_base' for assets and links
To allow reuse of this template as-is in libvirt-wiki, we need to be
able to specify a distinct asset_href_base and link_href_base. Adjust
the template to allow that.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2024-02-08 16:48:47 +01:00
Peter Krempa
334858bd40 docs: xsl: Properly propagate 'href_base' as XSL template parameter
Propagate it as a parameter both from site.xsl and from newapi.xsl, the
latter of which declared it as a variable.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2024-02-08 16:48:47 +01:00
Peter Krempa
464450772f docs: newapi: Remove unused 'docomponents' template
Never used since introduction in b38893c3ea

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
2023-06-02 09:39:10 +02:00
Michal Privoznik
6a15e22265 docs: newapi.xsl: Generate overall docs for enums too
There are/can be overall docs for enums (e.g.
virDomainModificationImpact) not just individual values. But
these never make it into the generated HTML which is a bit
unfortunate as they can contain valuable information for users.

Generate a block with overall enum documentation, just like we do
for functions.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2023-05-25 14:22:34 +02:00
Michal Privoznik
1fa7443dc7 docs: newapi.xsl: Generate docs on generic typedefs
We have plenty of generic typedefs (that basically just alias a
struct, or our popular virXXXPtr). Because we do not generate
HTML docs for it, the documentation is placed at random places,
e.g.: comment from virDomainPtr typedef ("a virDomainPtr is
pointer to a virDomain private structure ...") ends up after
virDomainProcessSignal enum block.

There are some less weird occurrences of this problem (e.g.
virBlkioParameterPtr), but yet - the typedef appears in TOC.

Therefore, generate a block for each typedef and put its
description there.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2023-05-25 14:22:13 +02:00
Peter Krempa
5ee27c37e6 docs: xsl: Simplify templating XSL
Wrap the auto-generated pages (API ref and hvsupport.html) in the proper
top level element similarly to what the pages generated from RST have to
remove the extra case when templating our web.

(Best viewed with 'git show -w')

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2023-05-18 10:06:51 +02:00
Peter Krempa
f11c773014 docs: newapi.xsl: Remove support for generating index page
Since we need to generate API docs for multiple input files the index
page is not useful for us and was replaced by a manual one. Drop the XSL
for generating it.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2023-05-18 10:06:51 +02:00
Peter Krempa
15be6660b3 docs/newapi.xsl: Take API flag data from libvirt-api.xml rather than access/libvirt-access.xml
Since now we embed the data in the libvirt API we don't need to source
it from the extra document.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2023-03-06 13:09:16 +01:00
Peter Krempa
91d890bdce docs/html: Properly generate ACL permissions into API reference
The 'newapi.xsl' stylesheet was referencing non-existing paths to the
XML files holding ACL permission flags for individual APIs. Additionally
the 'document()' XSL function doesn't even allow concatenation of the
path as it was done via '{$builddir}/src..', but requires either direct
argument or use of the 'concat()' function.

This meant that the 'acls' variable was always empty and thus none of
our API documentation was actually generated with the 'acl' section.

Fix it by passing the path to the XML via an argument to the stylesheet
as the files differ based on which document is being generated.

Since the 'admin' API does not have ACL we need to handle it separately
now in the build system.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2023-02-20 18:26:53 +01:00
Peter Krempa
cca6787b15 docs: xsl: Don't generate pointless index pages for qemu/admin/lxc API
The index page only really makes sense for the top level directory. The
specific index files are unreferenced since last commit. Drop them.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-11-03 14:11:22 +01:00
Peter Krempa
ed2109d272 docs: xsl: Don't format empty sections in API manual
The LXC module has no exported 'Types' but the XSL template which
generates the 'libvirt-libvirt-lxc.html' page would try to format it
anyways. This would result in an empty non-pair version of the '<pre>'
tag to be used in the page, which didn't render well with modern
browsers for some reason. All following sections would become children
of the non-pair <pre>.

Fix the XSL template to not generate empty 'Types' or 'Functions'
sections similarly to how we do with 'Macros'.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-11-03 14:11:22 +01:00
Peter Krempa
0097f2a36e docs: xsl: newapi: Remove unused 'navbar' template
The template is unused since commit 9092c3d491

Remove also the up|right|left|home.png files which were only used by
code generated by the unused template.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-11-03 14:11:22 +01:00
Peter Krempa
99d533c2aa docs: newapi: Consider also 'https://' links in the API generator XSL
We converted exclusively to https links so the generator should wrap
those in appropriate link tags too.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Jonathon Jongsma <jjongsma@redhat.com>
2022-09-01 13:11:09 +02:00
Michal Privoznik
bdd3dfba15 docs: Format @variable properly
When documenting our public API in some places we use '@' to
refer to the variable. For instance:

 * This API tries to set guest time to the given value. The time
 * to set (@seconds and @nseconds) should be in seconds relative
 * to the Epoch of 1970-01-01 00:00:00 in UTC.

However, when generating HTML documentation these tokens are
copied verbatim. What we can do is drop the '@' character and
wrap the variable in <code/> so that it is formatted properly.

Due to the way we 'parse' docs a token might actually be slightly
more than just '@variable'. For instance in the example above we
will have the following tokens: '(@seconds' and '@nseconds)'.
Thus we need to handle possible substring before and after
variable.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-09-15 08:37:40 +02:00
Daniel P. Berrangé
08376431b4 docs: fix libvirt go-import metadata in pages and links in 404 page
The meson conversion lost the <meta> tags providing the go-import,
because the "$pagename" variable lost the .html suffix. Rather
than fix that, just change to using "$pagesrc" instead, as it is a
better fit.

The 404 page also needs to use absolute links to work correctly for
pages in sub-folders.

Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-08-04 17:06:33 +01:00
Daniel P. Berrangé
eb7388b549 docs: relax CSS context match for pretty tables
We currently only render pretty tables if they have the "top_table"
class set. All of our tables set this, except for the ACL & migration
doc tables, which should have set it, and the API reference which does
not want it.

Simplify life by rendering all tables in a pretty style and remove the
need for the "top_table" class entirely. A small rule turns off the
pretty style for the API reference where tables are a hack used to
render enums with horizontal alignment.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-12-04 15:48:28 +00:00
Daniel P. Berrangé
eef089db78 docs: fix include of ACL permissions files
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>
2019-11-22 11:14:20 +00:00
Daniel P. Berrangé
0aa8536f14 docs: generate API reference pages for admin, qemu & lxc libraries
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-11-22 11:14:20 +00:00
Michal Privoznik
648c11c04c docs: Make anchors follow HTML5
According to HTML specification, <a name=''> works in HTML4, but
<a id=''> works in both HTML4 and HTML5. This is followed even in
docs/page.xsl where HTML bookmark links are generated only for
those anchors which have @id attribute.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-08-28 13:39:26 +02:00
Peter Krempa
5726e47234 docs: Make anchors in API html files clickable/linkable
Use 'id' instead of 'name' for anchors which adds the hidden clickable
headerlink helper so it's way simpler to link to a specific part of the
docs.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2019-08-16 13:16:18 +02:00
Peter Krempa
63cbad4e05 docs: Format bit shift and hex notation for bitwise flag enums
Big number itself does not make much sense in some cases. Format the
bitshift format as well.

Changes our web page docs from:

VIR_MIGRATE_POSTCOPY = 32768 : Setting the VIR_MIGRATE_POSTCOPY...
VIR_MIGRATE_TLS      = 65536 : Setting the VIR_MIGRATE_TLS flag...

to:

VIR_MIGRATE_POSTCOPY = 32768 (0x8000; 1 << 15)  : Setting the VIR_MIGRATE_POSTCOPY...
VIR_MIGRATE_TLS      = 65536 (0x10000; 1 << 16) : Setting the VIR_MIGRATE_TLS flag...

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
2019-01-31 12:02:35 +01:00
Daniel P. Berrange
17160a705a docs: generate pretty indented HTML for API docs
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-08-02 17:00:11 +01:00
Daniel P. Berrange
b1c81567c7 docs: switch to using HTML5 doctype declaration
The HTML5 doctype is simply

  <!DOCTYPE html>

no DTD is present because HTML5 is no longer defined as an
extension of SGML.

XSL has no way to natively output a doctype without a public
or system identifier, so we have to use an <xsl:text> hack
instead.

See also

  https://dev.w3.org/html5/html-author/#doctype-declaration

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-08-02 17:00:11 +01:00
Martin Kletzander
a54c962286 docs: Add build timestamps to generated html/php pages
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>
2017-07-26 17:47:25 +02:00
Michal Privoznik
099a5ef8f0 docs: Span cells if there's not doc text for enum val
When generating HTML documentation we put enum values into a
table so that we can display the value's name, numerical value
and description (if it has one). Now the last part is problem. If
the value doesn't have description the table row has just two
cells and if it has one the row counts three cells. This makes
HTML engines render the description into very little space - for
instance see:

  html/libvirt-libvirt-domain.html#virDomainMemoryStatTags

We can avoid this problem if we let the cell that corresponds to
numerical value span over two cells if there's no description.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
2017-07-24 12:08:02 +02:00
Claudio Bley
5eb3dff5b6 docs: generate links from plain text documentation
There are two forms used throughout libvirt code comments, which
are both supported by this patch.

* plain links like e.g. http://www.libvirt.org/
* links enclosed in <> characters, e.g. <http://www.libvirt.org/>

Signed-off-by: Claudio Bley <cbley@av-test.de>
2013-10-30 17:30:12 +01:00
Claudio Bley
d2ee3bbfa0 docs: add class "description" to div's containing descriptions 2013-10-30 17:30:11 +01:00
Claudio Bley
8213f6c38e docs: process code blocks similar to Markdown
Wrap pre-formatted example code in <code> elements. This works
similar to Markdown[1] code blocks[2]:

Every line indented with at least 2 spaces is considered a code
block and gets wrapped in <pre> and <code> tags.

Look at the documentation for e.g. virStreamSend for before-and-after
effects.

[1] http://daringfireball.net/projects/markdown/
[2] http://daringfireball.net/projects/markdown/syntax#precode
2013-10-30 17:30:11 +01:00
Jiri Denemark
0543e0d212 docs: Load libvirt_access*.xml from build dir
The xml files are generated in build directory and thus docs/newapi.xsl
was not able to find them in a VPATH build.

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
2013-09-23 14:16:45 +02:00
Daniel P. Berrange
da13f2c70c Add documentation for access control system
This adds two new pages to the website, acl.html describing
the general access control framework and permissions models,
and aclpolkit.html describing the use of polkit as an
access control driver.

page.xsl is modified to support a new syntax

  <div id="include" filename="somefile.htmlinc"/>

which will cause the XSL transform to replace that <div>
with the contents of 'somefile.htmlinc'. We use this in
the acl.html.in file, to pull the table of permissions
for each libvirt object. This table is autogenerated
from the enums in src/access/viraccessperms.h by the
genaclperms.pl script.

newapi.xsl is modified so that the list of permissions
checks shown against each API will link to the description
of the permissions in acl.html

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-08-09 17:13:02 +01:00
Daniel P. Berrange
664ab2801d Add info about access control checks into API reference
So that app developers / admins know what access control checks
are performed for each API, this patch extends the API docs
generator to include details of the ACLs for each.

The gendispatch.pl script is extended so that it generates
a simple XML describing ACL rules, eg.

  <aclinfo>
    ...
    <api name='virConnectNumOfDomains'>
      <check object='connect' perm='search_domains'/>
      <filter object='domain' perm='getattr'/>
    </api>
    <api name='virDomainAttachDeviceFlags'>
      <check object='domain' perm='write'/>
      <check object='domain' perm='save' flags='!VIR_DOMAIN_AFFECT_CONFIG|VIR_DOMAIN_AFFECT_LIVE'/>
      <check object='domain' perm='save' flags='VIR_DOMAIN_AFFECT_CONFIG'/>
    </api>
    ...
  </aclinfo>

The newapi.xsl template loads the XML files containing the ACL
rules and generates a short block of HTML for each API describing
the parameter checks and return value filters (if any).

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-08-08 11:59:46 +01:00
Daniel P. Berrange
5e7b0e8757 Fix namespace bugs in API docs, todo page & hv support page
The XSL for generating the API docs was missing the HTML5
namespace declarations. The todo and hvsupport scripts were
also missing the HTML5 doctype / namespace declaration.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-07 11:19:04 +01:00
Claudio Bley
52b1fd2582 docs: use div, not table, for notices on opaque types
It's simpler to render and it prevents wrapping the line too early
because of the table spacing, border et cetera.
2013-02-01 08:47:38 +01:00
Claudio Bley
cb022b6bc7 docs: don't use <i> and <tt> HTML tags
Use of <tt> is discouraged in HTML 4.x and has finally been obsoleted
in HTML 5. Likewise for the <i> tag.

Using tables for layout is (widely) considered bad style, too.

Use defintion lists, definition term and defintion description
elements instead.

Signed-off-by: Claudio Bley <cbley@av-test.de>
2013-01-18 15:36:38 +01:00
Claudio Bley
458dd20da9 docs: Assign classes to documentation elements
In CSS the following class names are available:

* keyword     (keywords like "typedef", "struct")
* type        (types like "int", "void*")
* comment     (comments after members of enums or structs)
* directive   (preprocessor directives, #define)
* undisclosed (text saying that the API is not public)

Additionally, kill all of the left-over "programlisting" class
assignments. There are no CSS rules for them.

Signed-off-by: Claudio Bley <cbley@av-test.de>
2013-01-18 15:36:38 +01:00
Claudio Bley
3b54b2e345 docs: break longer text into paragraphs in HTML
Libvirt's HTML documentation is not as easy to the eyes as it could
be since long text has no visual breaks.

Take advantage of the formatting in documentation comments and wrap
each part separated by two consecutive \n into a HTML <p> element.
2013-01-09 08:01:28 +01:00
Philipp Hahn
ce7244a014 Improve tokenizing of linkable terms
Currently only tabs and blanks are used for tokenizing the description,
which breaks when a term is at the end of a line or has () appended to
it.
1. Use also other white space characters such as new-lines and carriage
   return for splitting.
2. Remove some common non-word characters from the token before lookup.

Signed-off-by: Philipp Hahn <hahn@univention.de>
2011-08-12 07:35:19 -06:00
Daniel Veillard
d42ea21aec Fix to python API extractor and API doc generation
This fixes a number of issues most of them raised by Eric Blake on the
generated documentation output:
   - parsing of "long long int" and similar
   - add parsing of unions within a struct
   - remove spurious " * " fron comments on structure fields and enums
   - fix concatenation of base type and name in arrays
   - extend XSLT to cope with union in structs

* docs/apibuild.py: fix and extend API extraction tool
* docs/newapi.xsl: extend the stylesheets to cope with union in
  public structures
2011-06-22 15:50:08 +08:00
Daniel Veillard
5362edd442 Change generated HTML to UTF-8 encoding
* docs/ChangeLog.xsl docs/newapi.xsl docs/site.xsl: change all
  stylesheets to output UTF-8 HTML instead of ISO Latin 1 which was
  breaking on some people names.
2009-12-08 16:09:33 +01:00
Daniel P. Berrange
d62a9f2390 Adapt layout to workaround IE6 bugs 2008-04-25 16:23:51 +00:00
Daniel P. Berrange
9092c3d491 Split website out into one file per page. APply new layout and styling 2008-04-23 17:08:31 +00:00
Jim Meyering
e04912a9f0 Remove all trailing blanks; turn on the rule to detect them.
* Makefile.cfg (local-checks-to-skip): Remove sc_trailing_blank.
* .x-sc_trailing_blank: New file, to exempt the few binary files.
2008-02-05 19:27:37 +00:00
Daniel Veillard
b4c282a79b * docs/apibuild.py docs/newapi.xsl: fix generation of XML and
stylesheet
* docs/*: regenerated
* src/bridge.c src/bridge.h src/buf.c src/iptables.c src/libvirt.c
  src/qemu_driver.c src/qemu_driver.h src/uuid.c src/uuid.h: cleanup,
  addd comments, made functions static and fixe a few bugs
Daniel
2007-06-29 13:23:13 +00:00
Daniel Veillard
8c423e6c83 * //* : renamed the project libvirt , this affects all makefiles,
the specs, the icons, the docs, etc ...
* configure.in: prepare for 0.0.3
Daniel
2006-02-09 17:45:11 +00:00