Commit Graph

146 Commits

Author SHA1 Message Date
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. Berrangé
568a417224 Enforce a standard header file guard symbol name
Require that all headers are guarded by a symbol named

  LIBVIRT_$FILENAME

where $FILENAME is the uppercased filename, with all characters
outside a-z changed into '_'.

Note we do not use a leading __ because that is technically a
namespace reserved for the toolchain.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2018-12-14 10:47:13 +00:00
Daniel P. Berrangé
600462834f Remove all Author(s): lines from source file headers
In many files there are header comments that contain an Author:
statement, supposedly reflecting who originally wrote the code.
In a large collaborative project like libvirt, any non-trivial
file will have been modified by a large number of different
contributors. IOW, the Author: comments are quickly out of date,
omitting people who have made significant contribitions.

In some places Author: lines have been added despite the person
merely being responsible for creating the file by moving existing
code out of another file. IOW, the Author: lines give an incorrect
record of authorship.

With this all in mind, the comments are useless as a means to identify
who to talk to about code in a particular file. Contributors will always
be better off using 'git log' and 'git blame' if they need to  find the
author of a particular bit of code.

This commit thus deletes all Author: comments from the source and adds
a rule to prevent them reappearing.

The Copyright headers are similarly misleading and inaccurate, however,
we cannot delete these as they have legal meaning, despite being largely
inaccurate. In addition only the copyright holder is permitted to change
their respective copyright statement.

Reviewed-by: Erik Skultety <eskultet@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2018-12-13 16:08:38 +00:00
Radostin Stoyanov
c774562242 apibuild: Simplify getline()
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
437f1eadd4 apibuild: Remove redundant parentheses
http://pylint-messages.wikidot.com/messages:c0325

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
eb752c4675 apibuild: Simplify parsing string tokens
Improve readability and reduce the complexity of the code that is
searching for string tokens (i.e. characters surrounded by a single
or double quote).

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
c8d3bbaad0 apibuild: Simplify merging of preproc tokens
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
c3e611927c apibuild: Use list comprehension insteand of map
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
d2e226df5c apibuild: Simplify type checking of literals
Reduce the number of if-statements used to assign a literals
to corresponding class variables.

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
06462d7927 apibuild: Simplify parseTypeComment()
Improve readability and reduce complexity the method
parseTypeComment().

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
c57b56756a apibuild: Simplify strip_lead_star()
The method strip_lead_star() removes a single leading asterisk
character from a string by ignoring leading whitespace, otherwise it
returns the original string.

This could be achieved with a single if-statement followed by replace.

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
eb327e6c61 apibuild: Fix indentation not multiple of 4
PEP8 recommends that the number of spaces used for indentation of
Python code to be a multiple of four [1] [2].

1: https://lintlyci.github.io/Flake8Rules/rules/E111.html
2: https://lintlyci.github.io/Flake8Rules/rules/E114.html

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
aad30c3e57 apibuild: Drop backslash between brackets
Backslash between brackets in Python is redundant. [1]

1: https://lintlyci.github.io/Flake8Rules/rules/E502.html

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
ddfc6db2f5 apibuild: Avoid double sorting of ids
The uniq() function returns a sorted list, there is no need
to sort this list again.

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:36 +00:00
Radostin Stoyanov
e169caa462 apibuild: Simplify uniq function
Use a set (unordered collections of unique elements) [1] to remove
repeated elements in a list.

1: https://docs.python.org/3/tutorial/datastructures.html#sets

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:35 +00:00
Radostin Stoyanov
5e870cbda4 python: Remove space around = in keyword args
PEP8 recommends not having spaces around = in a keyword argument or
a default parameter value.

https://www.python.org/dev/peps/pep-0008/#other-recommendations

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:35 +00:00
Radostin Stoyanov
e390bb1571 apibuild: Simplify conditional statements
Improve readability by reducing the complexity and length of
conditional statements.

Example: The following condition:

	if (o >= 97 and o <= 122) or
	   (o >= 65 and o <= 90) or
	   (o >= 48 and o <= 57) or
	   (" \t(){}:;,+-*/%&!|[]=><".find(line[i]) == -1):

Will be True for every character that is not in string:
	" \t(){}:;,+-*/%&!|[]=><"

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:35 +00:00
Radostin Stoyanov
293bb82b58 python: Add whitespace around = and % operators
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:35 +00:00
Radostin Stoyanov
28593b5b54 apibuild: Remove whitespace before ', ' and ':'
PEP8 recommends removing whitespace immediately before a comma,
semicolon, or colon [1]. In addition remove multiple spaces after
keyword (PEP8 - E271).

1: https://www.python.org/dev/peps/pep-0008/#whitespace-in-expressions-and-statements

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:35 +00:00
Radostin Stoyanov
6d43a754af apibuild: Split imports on separate lines
PEP8 recommends imports to be on separate lines. [1]

1: https://www.python.org/dev/peps/pep-0008/#imports

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:35 +00:00
Radostin Stoyanov
80559e4879 apibuild: Use isinstance for type checking
The isinstance() function [1] returns true if an object argument is an
instance of a classinfo argument or of a direct, indirect subclass
thereof.

1: https://docs.python.org/3/library/functions.html#isinstance

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
2018-03-20 12:13:35 +00:00
Andrea Bolognani
677aaeb128 python: Drop explicit version where possible
Some of our scripts are known to work both with Python 2 and
Python 3, so for them we shouldn't be forcing any specific
version of the interpreter when they're called directly; we
always use $(PYTHON) explicitly in our build rules anyway.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2018-03-19 11:22:02 +01:00
Cole Robinson
e39a7cd256 apibuild: Fix -refs.xml building
Another usage of deprecated 'string' functions. We are just trying to
match ascii letters here, so use a simple regex. And again drop the
aggressive exception handling, it doesn't seem to trigger for anything
in libvirt code.

Signed-off-by: Cole Robinson <crobinso@redhat.com>
2018-03-16 15:07:23 -04:00
Cole Robinson
960ff97be3 apibuild: Fix errors on python3
Module 'string' function lower doesn't exist in python3. The canonical
way is to call .lower() on a str instance. Do that, and make the
exception handling more specific, which would have made this issue
obvious.

Signed-off-by: Cole Robinson <crobinso@redhat.com>
2018-03-16 15:07:18 -04:00
John Ferlan
8635b1f6b3 docs: Fix apibuild.py syntax
Commit id '477502de3' altered the entry to add one too many closing
parenthesis ')' and that propagated into commit id '9176b42bd'.

Signed-off-by: John Ferlan <jferlan@redhat.com>
2018-03-15 16:20:07 -04:00
Andrea Bolognani
e379dcce57 python3: Replace keys() + sort() with sorted()
The keys() method no longer returns a list, so converting the
return value would be necessary before calling sort() on it;
alternatively, we can just call sorted(), which returns a
sorted list.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2018-03-15 17:48:43 +01:00
Andrea Bolognani
9176b42bdb python3: Call list() explicitly as needed
For list concatenation to work, the value returned by the
keys() method must be converted to a list first.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2018-03-15 17:48:41 +01:00
Andrea Bolognani
477502de30 python3: Remove uses of string.*() functions
All of these have been replaced with methods.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2018-03-15 17:48:40 +01:00
Andrea Bolognani
71c0e130cd python3: Use the 'in' keyword
This replaces uses of the has_key() method.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2018-03-15 17:48:37 +01:00
Andrea Bolognani
7fad2b675a python3: Use the repr() function
This replaces the `` built-in.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2018-03-15 17:48:33 +01:00
Andrea Bolognani
b207817b49 python3: Use the print() function
It has replaced the 'print' statement.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2018-03-15 17:47:14 +01:00
Andrea Bolognani
f34fdd5ab6 python: Don't hardcode interpreter path
This is particularly useful on operating systems that don't ship
Python as part of the base system (eg. FreeBSD) while still working
just as well as it did before on Linux.

While at it, make it explicit that our scripts are only going to
work with Python 2, and remove the usage of unbuffered I/O, which
as far as I can tell has no effect on the output files.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
2017-09-19 16:04:53 +02:00
Michal Privoznik
6efdd94dbc apibuild.py: Handle enum comments properly
After f4cb85c6af we only have two options for placing enum
values descriptions. It's either:

    typedef enum {
        /* Some long description. Therefore it's placed before
         * the value. */
        VIR_ENUM_A_VAL = 1,
    } virEnumA;

or:

    typedef enum {
        VIR_ENUM_B_VAL = 1, /* Some short description */
    } virEnumB;

However, our apibuild.py script is not able to deal with the
former one. It messes up comments. To fix this couple of things
needs to be done:

a) DO NOT reset self.comment in parseEnumBlock(). This is a
result from our tokenizer. Upon calling token() if it finds a
comment block it stores it in self.comment and returns the next
token (which is not comment). Therefore, if we reset self.comment
we might lose the first comment in the enum block.

b) we need a variable to track if the current enum block uses
value descriptions before or after values. That is if it's type
virEnumA or virEnumB. Depending on that, it we're dealing with
virEnumA type and the current token is a comma ',' we can add the
value into the list as we already have everything needed:
comment, name and value.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
2017-07-24 12:03:33 +02:00
Guido Günther
214c226f9e Unbreak rebuilding docs with release tarballs
Release tarballs ship the include/libvirt/libvirt-common.h.

when srcdir != builddir we end up including libvirt-common.h twice: from
$top_srcdir/include/libvirt-common.h and from
$builddir/include/libvirt-common.h leading to

  function virTypedParamsGetUInt from /tmp/buildd/libvirt-2.4.0/debian/build/docs/../include/libvirt/libvirt-common.h redeclared in /tmp/buildd/libvirt-2.4.0/docs/../include/libvirt/libvirt-common.h
  function virTypedParamsAddBoolean from /tmp/buildd/libvirt-2.4.0/debian/build/docs/../include/libvirt/libvirt-common.h redeclared in /tmp/buildd/libvirt-2.4.0/docs/../include/libvirt/libvirt-common.h
   …

Only add the builddir to the search list if there is no pregenerated
libvirt-common.h.

Reuse the existing check that predates the libvirt.h → libvirt-common.h
split and that probably was meant for exactly that.

References: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=842452
2016-11-07 20:04:28 +01:00
Ján Tomko
ad9e72f5fa hvsupport: use a regex instead of XML::XPath
When generating the hvsupport.html.in file, we parse the -api.xml
files generated by apibuild.py to know in which HTML file the API
function is.

Doing an XPath query for every single 'function' element in the
file is inefficient.

Since the XML file is generated by another of our build scripts
(apibuild.py, using Python's standard 'output.write' XML library),
just find the function name->file mapping by a regex upfront.

Also add a note about this next to the line that generates it
in apibuild.py and do not check if XML::XPath is installed in
bootstrap since we no longer use it.
2016-07-19 18:42:44 +02:00
Michal Privoznik
3864d86385 apibuild: Substitute only pure number tokens
In 38df47c9af I've tried to prepare our apibuild.py script for
change made in 0628f3498c (1U << 31). What I've done in the
former commit was to replace \d+U in parsed tokens with \d.
Problem was, my regular expression there was not quite right as
it also translated VIR_123U_VAL into VIR_123_VAL.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-05-30 15:38:07 +02:00
Michal Privoznik
38df47c9af docs: Teach apibuild to deal with (1U << 31) too
The apibuild script is a terrifying beast that parses some source
files of ours and produces an XML representation of them. When it
comes to parsing enums we have in some header files, it tries to
be clever and detect a value that an enum member has (or if it is
an alias for a different member). Whilst doing that it has to
deal with values we give to the members in many formats. At some
places we just pass the value in decimal:

    VIR_DOMAIN_BLOCK_JOB_TYPE_PULL = 1,

in other places, we use the aliasing:

    VIR_CONNECT_GET_ALL_DOMAINS_STATS_ACTIVE = VIR_CONNECT_LIST_DOMAINS_ACTIVE,

and in other places bitwise shifts are used:

    VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS = 1 << 31, /* enforce requested stats */

The script tries to parse all of these resulting in the following
tokens: "1", "VIR_CONNECT_LIST_DOMAINS_ACTIVE", "1<<31"; Then, the
script tries to turn these into integers using python's eval()
function. This function succeeds on the first and the last
tokens. But, if we were to modify the last example so that it's
of the following form:

    VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS = 1U << 31, /* enforce requested stats */

the token representing enum's member value will then be "1U<<31".
So our parsing is good. Unfortunately, python is not aware of the
difference between signed and unsigned C types, therefore eval()
fails over this token and the parser falls back thinking it's an
alias to another enum member. Well it's not.

The solution is to transform [0-9]U into [0-9] as for our
purposes here it's the same thing.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-05-28 13:21:43 +02:00
Andrea Bolognani
cb44737165 apibuild: Fix method call 2016-04-26 09:20:12 +02:00
Andrea Bolognani
4a98ebb07c apibuild: Introduce app class
All top-level functions have been moved to this class.

On top of that, the app.warning() method has been defined,
so that calls to it - already present in rebuild() - can
actually succeed.
2016-04-26 09:20:12 +02:00
Andrea Bolognani
ccaceab7bd apibuild: Add index.warning() method
This method is used in eg. index.merge(), but is not defined
anywhere. The implementation has been copied from docBuilder.
2016-04-26 09:20:12 +02:00
Peter Krempa
d195cffa2e docs: apibuild: Fix VPATH build
libvirt-common.h is generated into builddir/include/libvirt. apibuild.py
only operated on srcdir/inlcude/libvirt. With VPATH build
srcdir/docs/libvirt-libvirt-common.html would not get generated and make
RPM failed.
2016-04-25 08:49:30 +02:00
Peter Krempa
2f745b63fd docs: apibuild: Fix for python 2.6
Ancient python didn't like the new list added in 99283874. Convert it to
a dict.
2016-04-22 10:14:13 +02:00
Peter Krempa
9928387473 api: Generate docs for libvirt-common.h
Since commit f5d9c5d00c moved the virTypedParam stuff into
libvirt-common we did not generate any docs for them and neither did we
populate them into libvirt-api.xml. This broke the sanity check in
libvirt python. Fix it by generating docs for libvirt-common.h too.
2016-04-21 15:39:08 +02:00
Peter Krempa
a253396a47 apibuild: Allow completely skipping certain macros
Some macros don't make sense to be documented at all. Add infrastructure
to the web/api generator and add VIR_DEPRECATED and VIR_EXPORT_VAR as
macros we should not document.
2016-04-21 15:39:08 +02:00
Jiri Denemark
9d0a2af6c2 Introduce virErrorCopyNew
A helper function for copying error objects.

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
2015-07-10 11:47:13 +02:00
Martin Kletzander
878bf2a3c9 Add XML files with admin API specification
No online docs are build from it since it doesn't really fit into our
document structure and new page will need to be created for it, but this
is at least a heads-up commit for easier parsing in order to build some
documentation (or python bindings) later on.

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
2015-06-16 13:46:20 +02:00
Jiri Denemark
b6a2639bd2 apibuild: Generate macro/@string attribute
If a macro has a string value, the @string attribute will contain the
value. Otherwise @string attribute will be missing.

For example, the following macro definition from libvirt-domain.h:

 /**
  * VIR_MIGRATE_PARAM_URI:
  * ...
  */
 # define VIR_MIGRATE_PARAM_URI               "migrate_uri"

will result in

 <macro name='VIR_MIGRATE_PARAM_URI' file='libvirt-domain' string='migrate_uri'>
   <info><![CDATA[...]]></info>
 </macro>

https://bugzilla.redhat.com/show_bug.cgi?id=1229199

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
2015-06-11 13:52:52 +02:00
Jiri Denemark
ee3b344d60 apibuild: Fix indentation
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
2015-06-11 13:52:52 +02:00
Daniel P. Berrange
64702ac367 Fix handling of whitespae in preprocessor macros for API generator
The apibuild.py script did not handle whitespace in preprocessor
macros, so it failed to detect constants declared with '# define'
instead of '#define'. Since we now correctly indent our public
header files, we have silently lost all constants from
libvirt-api.xml. This also caused us to not detect formatting
errors in constant docs
2014-12-04 15:00:30 +00:00
Daniel P. Berrange
47fb613873 Fix API docs for header file re-organization
The API docs generators were broken by the header file
re-organization. Specifically

 * html/libvirt-libvirt.html was empty (and should be deleted)
 * Makefile.am didn't install html/libvirt-libvirt-*.html
 * hvsupport.html was mostly empty
 * sitemap.html.in didn't list the new html/*.html files
2014-11-13 10:20:26 +00:00