1
0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-25 01:34:11 +03:00
Commit Graph

36 Commits

Author SHA1 Message Date
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
Daniel Veillard
ff97523083 * doc//*: mostly finished the revamp in the plane, starts to look good
Daniel
2006-01-21 23:34:36 +00:00
Daniel Veillard
76777c51f7 * doc/* : total revamp of the web site based on Diana Fong design
but not completely integrated yet
Daniel
2006-01-20 15:49:04 +00:00
Daniel Veillard
e784908cfe Fixing doc generation stylesheets, daniel 2005-12-09 14:33:38 +00:00
Daniel Veillard
2380f6b269 Update of the docs, daniel 2005-12-08 23:49:08 +00:00
Daniel Veillard
b38893c3ea * configure.in libvir.spec.in docs/Makefile.am: make sure the
docs are installed and packaged in the -devel RPM
* docs/api.xsl docs/newapi.xsl: forgot to commit API HTML stylesheets
Daniel
2005-12-07 13:45:20 +00:00