3:51 p.m.
Improve the checker tool to also track orphaned pages and check presence
and usage of images. In addition to that this series fixes handful of
instances of the problems that the script caught.
This series adds two documents:
- docs/logos/README.rst (converted into docs/logos/index.html)
The page shows all logos which libvirt has. It's now linked from the
docs page.
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/3770134533/artifacts/website/l...
- docs/golang.rst
The page ties together the 4 go module pages we have which were not
linked and is linked from docs.html
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/3770134533/artifacts/website/g...
Peter Krempa (9):
docs: XSL: Add source document name as custom data attribute for
<html>
scripts: check-html-references: Rename --prefix to --webroot and make
it mandatory
scripts: check-html-references: Improve error messages and don't mess
with relative paths
docs: manpages: Add missing manpages to index
docs: Add sub-page for all golang modules
scripts: check-html-references: Detect pages that are not linked to
kbase: eventloop: Fix path to referenced images
docs: logos: Turn 'README' into rST, generate an index and link to
images
scripts: check-html-refernces: Add checking for image file usage
docs/docs.rst | 5 +-
docs/golang.rst | 21 +++
docs/kbase/internals/eventloop.rst | 4 +-
docs/logos/README | 98 --------------
docs/logos/README.rst | 166 ++++++++++++++++++++++++
docs/logos/meson.build | 47 +++++++
docs/manpages/index.rst | 3 +
docs/meson.build | 3 +-
docs/page.xsl | 2 +-
scripts/check-html-references.py | 198 +++++++++++++++++++++++------
10 files changed, 406 insertions(+), 141 deletions(-)
create mode 100644 docs/golang.rst
delete mode 100644 docs/logos/README
create mode 100644 docs/logos/README.rst
--
2.39.1
3:51 p.m.
New subject: [PATCH 1/9] docs: XSL: Add source document name as custom data attribute for <html>
The html standard allows custom data attributes on any element in the
format of 'data-*' which are not interpreted. We can use it to embed the
name of the source document used to generate the page so that our
checker tools can use the friendly name.
https://html.spec.whatwg.org/multipage/dom.html#embedding-custom-non-visi...
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/page.xsl | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/page.xsl b/docs/page.xsl
index 548d5a11c4..20b49d1afd 100644
--- a/docs/page.xsl
+++ b/docs/page.xsl
@@ -80,7 +80,7 @@
<xsl:param name="timestamp"/>
<xsl:text disable-output-escaping="yes"><!DOCTYPE
html>
</xsl:text>
- <html>
+ <html data-sourcedoc="{$pagesrc}">
<xsl:comment>
This file is autogenerated from <xsl:value-of
select="$pagesrc"/>
Do not edit this file. Changes will be lost.
--
2.39.1
4:57 a.m.
New subject: [PATCH 1/9] docs: XSL: Add source document name as custom data attribute for <html>
On Tue, Feb 14, 2023 at 10:51:09PM +0100, Peter Krempa wrote:
The html standard allows custom data attributes on any element in
the
format of 'data-*' which are not interpreted. We can use it to embed the
name of the source document used to generate the page so that our
checker tools can use the friendly name.
https://html.spec.whatwg.org/multipage/dom.html#embedding-custom-non-visi...
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/page.xsl | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
With regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
3:51 p.m.
New subject: [PATCH 2/9] scripts: check-html-references: Rename --prefix to --webroot and make it mandatory
Force users to pass the path to the root of the webpage the script
should check. The script lives in a different subdirectory so the
default of the current directory doesn't make much sense.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/meson.build | 2 +-
scripts/check-html-references.py | 6 +++---
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/meson.build b/docs/meson.build
index 5c0c762db1..5ffd39c01b 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -359,7 +359,7 @@ test(
python3_prog,
args: [
check_html_references_prog.full_path(),
- '--prefix',
+ '--webroot',
meson.project_build_root() / 'docs'
],
env: runutf8,
diff --git a/scripts/check-html-references.py b/scripts/check-html-references.py
index 95a61a6bb4..6d9116585e 100755
--- a/scripts/check-html-references.py
+++ b/scripts/check-html-references.py
@@ -127,14 +127,14 @@ def check_targets(targets, anchors):
parser = argparse.ArgumentParser(description='HTML reference checker')
-parser.add_argument('--prefix', default='.',
- help='build tree prefix')
+parser.add_argument('--webroot', required=True,
+ help='path to the web root')
parser.add_argument('--external', action="store_true",
help='print external references instead')
args = parser.parse_args()
-files = get_file_list(args.prefix)
+files = get_file_list(args.webroot)
targets, anchors = process_all(files)
--
2.39.1
4:58 a.m.
New subject: [PATCH 2/9] scripts: check-html-references: Rename --prefix to --webroot and make it mandatory
On Tue, Feb 14, 2023 at 10:51:10PM +0100, Peter Krempa wrote:
Force users to pass the path to the root of the webpage the script
should check. The script lives in a different subdirectory so the
default of the current directory doesn't make much sense.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/meson.build | 2 +-
scripts/check-html-references.py | 6 +++---
2 files changed, 4 insertions(+), 4 deletions(-)
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
With regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
3:51 p.m.
New subject: [PATCH 3/9] scripts: check-html-references: Improve error messages and don't mess with relative paths
Now that we have the source file name as a custom attribute we can use
it to report which file actually needs to be edited to fix the error:
ERROR: 'docs/uri.rst': broken link to: 'drvqemu.html#exaple'
rather than:
broken link targets:
docs/uri.html broken link: drvqemu.html#exaple
which pointed to file which does not exist in the source directory.
This also allows us to delete all the relative path handling needed to
report at least somewhat user-legible errors before.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
scripts/check-html-references.py | 46 +++++++++++++-------------------
1 file changed, 19 insertions(+), 27 deletions(-)
diff --git a/scripts/check-html-references.py b/scripts/check-html-references.py
index 6d9116585e..8e726928e0 100755
--- a/scripts/check-html-references.py
+++ b/scripts/check-html-references.py
@@ -30,13 +30,6 @@ def get_file_list(prefix):
filelist = []
for root, dir, files in os.walk(prefix):
- prefixbase = os.path.dirname(prefix)
-
- if root.startswith(prefixbase):
- relroot = root[len(prefixbase):]
- else:
- relroot = root
-
for file in files:
if not re.search('\\.html$', file):
continue
@@ -45,20 +38,21 @@ def get_file_list(prefix):
if '404.html' in file:
continue
- fullfilename = os.path.join(root, file)
- relfilename = os.path.join(relroot, file)
- filelist.append((fullfilename, relfilename))
+ filelist.append(os.path.join(root, file))
return filelist
# loads an XHTML and extracts all anchors, local and remote links for the one file
-def process_file(filetuple):
- filename, relfilename = filetuple
+def process_file(filename):
tree = ET.parse(filename)
root = tree.getroot()
+ docname = root.get('data-sourcedoc')
- anchors = [relfilename]
+ if not docname:
+ docname = filename
+
+ anchors = [filename]
targets = []
for elem in root.findall('.//html:a', ns):
@@ -66,30 +60,30 @@ def process_file(filetuple):
an = elem.get('id')
if an:
- anchors.append(relfilename + '#' + an)
+ anchors.append(filename + '#' + an)
if target:
if re.search('://', target):
externallinks.append(target)
elif target[0] != '#' and 'mailto:' not in target:
- dirname = os.path.dirname(relfilename)
- targetname = os.path.normpath(os.path.join(dirname, target))
+ dirname = os.path.dirname(filename)
+ targetfull = os.path.normpath(os.path.join(dirname, target))
- targets.append((targetname, filename, target))
+ targets.append((filename, docname, targetfull, target))
# older docutils generate "<div class='section'"
for elem in root.findall('.//html:div/[@class=\'section\']', ns):
an = elem.get('id')
if an:
- anchors.append(relfilename + '#' + an)
+ anchors.append(filename + '#' + an)
# modern docutils generate a <section element
for elem in root.findall('.//html:section', ns):
an = elem.get('id')
if an:
- anchors.append(relfilename + '#' + an)
+ anchors.append(filename + '#' + an)
return (anchors, targets)
@@ -98,8 +92,8 @@ def process_all(filelist):
anchors = []
targets = []
- for filetuple in filelist:
- anchor, target = process_file(filetuple)
+ for file in filelist:
+ anchor, target = process_file(file)
targets = targets + target
anchors = anchors + anchor
@@ -109,17 +103,15 @@ def process_all(filelist):
def check_targets(targets, anchors):
errors = []
- for target, targetfrom, targetorig in targets:
+ for _, docname, target, targetorig in targets:
if target not in anchors:
- errors.append((targetfrom, targetorig))
+ errors.append((docname, targetorig))
if errors:
errors.sort()
- print('broken link targets:')
-
for file, target in errors:
- print(file + " broken link: " + target)
+ print(f'ERROR: \'{file}\': broken link to:
\'{target}\'')
return True
@@ -134,7 +126,7 @@ parser.add_argument('--external',
action="store_true",
args = parser.parse_args()
-files = get_file_list(args.webroot)
+files = get_file_list(os.path.abspath(args.webroot))
targets, anchors = process_all(files)
--
2.39.1
4:59 a.m.
New subject: [PATCH 3/9] scripts: check-html-references: Improve error messages and don't mess with relative paths
On Tue, Feb 14, 2023 at 10:51:11PM +0100, Peter Krempa wrote:
Now that we have the source file name as a custom attribute we can
use
it to report which file actually needs to be edited to fix the error:
ERROR: 'docs/uri.rst': broken link to: 'drvqemu.html#exaple'
rather than:
broken link targets:
docs/uri.html broken link: drvqemu.html#exaple
which pointed to file which does not exist in the source directory.
This also allows us to delete all the relative path handling needed to
report at least somewhat user-legible errors before.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
scripts/check-html-references.py | 46 +++++++++++++-------------------
1 file changed, 19 insertions(+), 27 deletions(-)
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
With regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
3:51 p.m.
New subject: [PATCH 4/9] docs: manpages: Add missing manpages to index
The manpages for 'virt-pki-query-dn', 'virt-qemu-qmp-proxy' and
'virt-ssh-helper.rst' were not referenced from the manpage index or any
other place.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/manpages/index.rst | 3 +++
1 file changed, 3 insertions(+)
diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst
index 8fd0d90041..e28c8e2f54 100644
--- a/docs/manpages/index.rst
+++ b/docs/manpages/index.rst
@@ -42,6 +42,9 @@ Tools
* `virsh(1) <virsh.html>`__ - management user interface
* `virt-qemu-run(1) <virt-qemu-run.html>`__ - run standalone QEMU instances
* `libvirt-guests(8) <libvirt-guests.html>`__ - suspend/resume running libvirt
guests
+* `virt-pki-query-dn(1) <virt-pki-query-dn.html>`__ - extract Distinguished Name
from a PEM certificate
+* `virt-ssh-helper(8) <virt-ssh-helper.html>`__ - libvirt socket proxy (internal
helper tool)
+* `virt-qemu-qmp-proxy(1) <virt-qemu-qmp-proxy.html>`__ - Expose a QMP proxy server
for a libvirt QEMU guest
Key codes
=========
--
2.39.1
4:59 a.m.
New subject: [PATCH 4/9] docs: manpages: Add missing manpages to index
On Tue, Feb 14, 2023 at 10:51:12PM +0100, Peter Krempa wrote:
The manpages for 'virt-pki-query-dn',
'virt-qemu-qmp-proxy' and
'virt-ssh-helper.rst' were not referenced from the manpage index or any
other place.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/manpages/index.rst | 3 +++
1 file changed, 3 insertions(+)
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
With regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
3:51 p.m.
New subject: [PATCH 5/9] docs: Add sub-page for all golang modules
Our documentation has pages for 4 go modules, 2 current and 2 obsolete
ones, but points only to one of them and directly to golang's docs page.
Add a sub-page where all 4 sub-pages for the modules are linked.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/docs.rst | 2 +-
docs/golang.rst | 21 +++++++++++++++++++++
docs/meson.build | 1 +
3 files changed, 23 insertions(+), 1 deletion(-)
create mode 100644 docs/golang.rst
diff --git a/docs/docs.rst b/docs/docs.rst
index a826bd128c..855ce6a069 100644
--- a/docs/docs.rst
+++ b/docs/docs.rst
@@ -79,7 +79,7 @@ Application development
`Language bindings and API modules <bindings.html>`__
Bindings of the libvirt API for
`c# <csharp.html>`__,
- `go <https://pkg.go.dev/libvirt.org/go/libvirt>`__,
+ `go <https://pkg.go.dev/libvirt.org/go/libvirt>`__ (`all go modules
<golang.html>`__),
`java <java.html>`__,
`ocaml <https://libvirt.org/ocaml/>`__,
`perl <https://search.cpan.org/dist/Sys-Virt/>`__,
diff --git a/docs/golang.rst b/docs/golang.rst
new file mode 100644
index 0000000000..77821cee24
--- /dev/null
+++ b/docs/golang.rst
@@ -0,0 +1,21 @@
+====================
+Go Language bindings
+====================
+
+Modern libvirt API bindings with Go modules
+-------------------------------------------
+
+The libvirt API bindings package and module for XML manipulation:
+
+ - `libvirt.org/go/libvirt <go/libvirt.html>`__ package
https://pkg.go.dev/libvirt.org/go/libvirt
+ - `libvirt.org/go/libvirtxml <go/libvirtxml.html>`__ package
https://pkg.go.dev/libvirt.org/go/libvirtxml
+
+
+Obsolete libvirt language bindings
+----------------------------------
+
+The following two go packages were superseded, but software currently using them
+No further development will take place.
+
+ - `libvirt.org/libvirt-go <libvirt-go.html>`__ - CGo binding to the native API
+ - `libvirt.org/libvirt-go-xml <libvirt-go-xml.html>`)) - annotated Go struct
definitions for XML handling
diff --git a/docs/meson.build b/docs/meson.build
index 5ffd39c01b..a90c59866a 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -80,6 +80,7 @@ docs_rst_files = [
'formatstorageencryption',
'glib-adoption',
'goals',
+ 'golang',
'governance',
'hacking',
'hooks',
--
2.39.1
5:02 a.m.
New subject: [PATCH 5/9] docs: Add sub-page for all golang modules
On Tue, Feb 14, 2023 at 10:51:13PM +0100, Peter Krempa wrote:
Our documentation has pages for 4 go modules, 2 current and 2
obsolete
ones, but points only to one of them and directly to golang's docs page.
Add a sub-page where all 4 sub-pages for the modules are linked.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/docs.rst | 2 +-
docs/golang.rst | 21 +++++++++++++++++++++
docs/meson.build | 1 +
3 files changed, 23 insertions(+), 1 deletion(-)
create mode 100644 docs/golang.rst
diff --git a/docs/golang.rst b/docs/golang.rst
new file mode 100644
index 0000000000..77821cee24
--- /dev/null
+++ b/docs/golang.rst
@@ -0,0 +1,21 @@
+====================
+Go Language bindings
+====================
+
+Modern libvirt API bindings with Go modules
+-------------------------------------------
+
+The libvirt API bindings package and module for XML manipulation:
+
+ - `libvirt.org/go/libvirt <go/libvirt.html>`__ package
https://pkg.go.dev/libvirt.org/go/libvirt
+ - `libvirt.org/go/libvirtxml <go/libvirtxml.html>`__ package
https://pkg.go.dev/libvirt.org/go/libvirtxml
+
+
+Obsolete libvirt language bindings
+----------------------------------
+
+The following two go packages were superseded, but software currently using them
Missing words at the end
+No further development will take place.
+
+ - `libvirt.org/libvirt-go <libvirt-go.html>`__ - CGo binding to the native API
+ - `libvirt.org/libvirt-go-xml <libvirt-go-xml.html>`)) - annotated Go struct
definitions for XML handling
If that above is fixed in some obvious manner
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
With regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
3:51 p.m.
New subject: [PATCH 6/9] scripts: check-html-references: Detect pages that are not linked to
Prevent sub-pages without a way to reach them.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
scripts/check-html-references.py | 57 ++++++++++++++++++++++++++++++++
1 file changed, 57 insertions(+)
diff --git a/scripts/check-html-references.py b/scripts/check-html-references.py
index 8e726928e0..4f08feab59 100755
--- a/scripts/check-html-references.py
+++ b/scripts/check-html-references.py
@@ -40,6 +40,8 @@ def get_file_list(prefix):
filelist.append(os.path.join(root, file))
+ filelist.sort()
+
return filelist
@@ -118,9 +120,54 @@ def check_targets(targets, anchors):
return False
+def check_usage_crawl(page, targets, visited):
+ visited.append(page)
+
+ tocrawl = []
+
+ for filename, docname, target, _ in targets:
+ if page != filename:
+ continue
+
+ targetpage = target.split("#", 1)[0]
+
+ if targetpage not in visited and targetpage not in tocrawl:
+ tocrawl.append(targetpage)
+
+ for crawl in tocrawl:
+ check_usage_crawl(crawl, targets, visited)
+
+
+# crawls the document references starting from entrypoint and tries to find
+# unreachable pages
+def check_usage(targets, files, entrypoint):
+ visited = []
+ fail = False
+
+ check_usage_crawl(entrypoint, targets, visited)
+
+ for file in files:
+ if file not in visited:
+ brokendoc = file
+
+ for filename, docname, _, _ in targets:
+ if filename != file:
+ continue
+ if docname:
+ brokendoc = docname
+ break
+
+ print(f'ERROR: \'{brokendoc}\': is not referenced from
anywhere')
+ fail = True
+
+ return fail
+
+
parser = argparse.ArgumentParser(description='HTML reference checker')
parser.add_argument('--webroot', required=True,
help='path to the web root')
+parser.add_argument('--entrypoint', default="index.html",
+ help='file name of web entry point relative to --webroot')
parser.add_argument('--external', action="store_true",
help='print external references instead')
@@ -128,8 +175,12 @@ args = parser.parse_args()
files = get_file_list(os.path.abspath(args.webroot))
+entrypoint = os.path.join(os.path.abspath(args.webroot), args.entrypoint)
+
targets, anchors = process_all(files)
+fail = False
+
if args.external:
prev = None
externallinks.sort()
@@ -140,6 +191,12 @@ if args.external:
prev = ext
else:
if check_targets(targets, anchors):
+ fail = True
+
+ if check_usage(targets, files, entrypoint):
+ fail = True
+
+ if fail:
sys.exit(1)
sys.exit(0)
--
2.39.1
5:03 a.m.
New subject: [PATCH 6/9] scripts: check-html-references: Detect pages that are not linked to
On Tue, Feb 14, 2023 at 10:51:14PM +0100, Peter Krempa wrote:
Prevent sub-pages without a way to reach them.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
scripts/check-html-references.py | 57 ++++++++++++++++++++++++++++++++
1 file changed, 57 insertions(+)
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
With regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
3:51 p.m.
New subject: [PATCH 7/9] kbase: eventloop: Fix path to referenced images
The images are referenced from '../images/' but the document is two
layers deep thus '../../images' needs to be used
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/kbase/internals/eventloop.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/kbase/internals/eventloop.rst b/docs/kbase/internals/eventloop.rst
index 856cabc85f..c7770614a1 100644
--- a/docs/kbase/internals/eventloop.rst
+++ b/docs/kbase/internals/eventloop.rst
@@ -23,7 +23,7 @@ desired function. If generalized, this is how many long running
programs
(daemons) work. Even those who are not waiting for direct user input and have no
graphical interface. Such as Libvirt.
-.. image:: ../images/event_loop_simple.png
+.. image:: ../../images/event_loop_simple.png
:alt: event loop
In Libvirt this approach is used in combination with ``poll(2)`` as all the
@@ -57,7 +57,7 @@ a message event loop is blocked and for an outside observer
unresponsive. This
is not acceptable for Libvirt. Therefore we have came up with the following
solution.
-.. image:: ../images/event_loop_worker.png
+.. image:: ../../images/event_loop_worker.png
:alt: event loop
The event loop does only necessary minimum and hand over message processing to
--
2.39.1
5:04 a.m.
New subject: [PATCH 7/9] kbase: eventloop: Fix path to referenced images
On Tue, Feb 14, 2023 at 10:51:15PM +0100, Peter Krempa wrote:
The images are referenced from '../images/' but the document
is two
layers deep thus '../../images' needs to be used
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/kbase/internals/eventloop.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
With regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
3:51 p.m.
New subject: [PATCH 8/9] docs: logos: Turn 'README' into rST, generate an index and link to images
The logo directory wasn't really referenced from anywhere. Additionally
there wasn't any reasonable index for all the image files which we have.
Turn the README file into rST and display the images it references. Link
to the new index file from the docs page.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/docs.rst | 3 +
docs/logos/README | 98 ------------------------
docs/logos/README.rst | 166 +++++++++++++++++++++++++++++++++++++++++
docs/logos/meson.build | 47 ++++++++++++
4 files changed, 216 insertions(+), 98 deletions(-)
delete mode 100644 docs/logos/README
create mode 100644 docs/logos/README.rst
diff --git a/docs/docs.rst b/docs/docs.rst
index 855ce6a069..ea14555575 100644
--- a/docs/docs.rst
+++ b/docs/docs.rst
@@ -163,3 +163,6 @@ Project development
`New repo setup <newreposetup.html>`__
Procedure for configuring new git repositories for libvirt
+
+`Libvirt logos <logos/index.html>`__
+ Libvirt logo files and guideline how to use them
diff --git a/docs/logos/README b/docs/logos/README
deleted file mode 100644
index 64dee41ec8..0000000000
--- a/docs/logos/README
+++ /dev/null
@@ -1,98 +0,0 @@
- Libvirt Logo README
- ===================
-
-The master SVG files were created in InkScape, using the Overpass font from Red
-Hat:
-
- https://overpassfont.org/
-
-
-Logo formats
-============
-
-The following SVG files are provided, along with standard bitmap sizes in PNG
-format:
-
- - logo-base.svg
-
- The basic "sardine tin" graphic used to create the other forms of the
- libvirt logo.
-
- The tin is rotated by 20 degrees, so its angle matches the angle of the left
- side of the letter "v" in the Overpass font
-
- Never use this logo file directly. It exists merely as a base for building
- the other logos
-
-
- - logo-square.svg
-
- The minimal square format logo for libvirt. Simply embeds the word
"libvirt"
- into the basic logo graphic.
-
- This is intended for use where a compact, square format representation of
- the logo is required.
-
- Bitmap sizes: 64, 128, 192, 256 px square
-
-
- - logo-square-powered.svg
-
- A variant of the square logo for use by 3rd party applications, to advertise
- their use of libvirt.
-
- Bitmap sizes: 64, 128, 192, 256 px square
-
-
- - logo-banner-light.svg
-
- A wide banner format of the logo. Embeds the words "libvirt virtualization
- API" into the basic logo graphic. The text is rendered in a light color, so
- suitable for placement over a dark background.
-
- Bitmap sizes: 257x92, 800x286 px
-
-
- - logo-banner-dark.svg
-
- A wide banner format of the logo. Embeds the words "libvirt virtualization
- API" into the basic logo graphic. The text is rendered in a dark color, so
- suitable for placement over a light background.
-
- Bitmap sizes: 257x92, 800x286 px
-
-
- - logo-sticker-square.svg
-
- A logo formatted into a square shape with outline, suitable for printing
- as a sticker. See https://github.com/terinjokes/StickerConstructorSpec
-
-
- - logo-sticker-hexagon.svg
-
- A logo formatted into a hexagon shape with outline, suitable for printing
- as a sticker. See https://github.com/terinjokes/StickerConstructorSpec
-
-
-PNG file creation
-=================
-
-The bitmap images should not be created in Inkscape, since its anti-aliasing of
-the rendered bitmaps is too aggressive, resulting in fuzzy images. Instead the
-GIMP is used to create bitmaps as follows:
-
- - File -> Open, select the SVG file
-
- When prompted for the image size, enter 1024 as the width and allow height
- to be auto-set based on aspect ratio
-
- - Image -> Scale Image
-
- Enter desired final bitmap size and use "Cubic" as scaling method.
-
- - File -> Export As
-
-
-It is important to let GIMP render initially at 1024 and then scale down, rather
-than rendering directly at the target size, since this the manual scaling step
-produces better quality
diff --git a/docs/logos/README.rst b/docs/logos/README.rst
new file mode 100644
index 0000000000..4b03d3aad1
--- /dev/null
+++ b/docs/logos/README.rst
@@ -0,0 +1,166 @@
+===================
+Libvirt Logo README
+===================
+
+The master SVG files were created in InkScape, using the Overpass font from Red
+Hat:
+
+ https://overpassfont.org/
+
+
+.. contents::
+
+
+Logo formats
+============
+
+The following SVG files are provided, along with standard bitmap sizes in PNG
+format:
+
+``logo-base.svg``
+-----------------
+
+.. image:: logo-base.svg
+
+The basic "sardine tin" graphic used to create the other forms of the
+libvirt logo.
+
+The tin is rotated by 20 degrees, so its angle matches the angle of the left
+side of the letter "v" in the Overpass font
+
+Never use this logo file directly. It exists merely as a base for building
+the other logos
+
+``logo-square.svg``
+-------------------
+
+.. image:: logo-square.svg
+
+The minimal square format logo for libvirt. Simply embeds the word "libvirt"
+into the basic logo graphic.
+
+This is intended for use where a compact, square format representation of
+the logo is required.
+
+Bitmap sizes: 96, 128, 192, 256 px square
+
+- 96px:
+
+.. image:: logo-square-96.png
+
+- 128px:
+
+.. image:: logo-square-128.png
+
+- 192px:
+
+.. image:: logo-square-192.png
+
+- 256px:
+
+.. image:: logo-square-256.png
+
+
+
+``logo-square-powered.svg``
+---------------------------
+
+.. image:: logo-square-powered.svg
+
+A variant of the square logo for use by 3rd party applications, to advertise
+their use of libvirt.
+
+Bitmap sizes: 96, 128, 192, 256 px square
+
+- 96px:
+
+.. image:: logo-square-powered-96.png
+
+- 128px:
+
+.. image:: logo-square-powered-128.png
+
+- 192px:
+
+.. image:: logo-square-powered-192.png
+
+- 256px:
+
+.. image:: logo-square-powered-256.png
+
+``logo-banner-light.svg``
+-------------------------
+
+.. image:: logo-banner-light.svg
+
+A wide banner format of the logo. Embeds the words "libvirt virtualization
+API" into the basic logo graphic. The text is rendered in a light color, so
+suitable for placement over a dark background.
+
+Bitmap sizes: 256x92, 800x286 px
+
+- 256x92px:
+
+.. image:: logo-banner-light-256.png
+
+- 800x286px:
+
+.. image:: logo-banner-light-800.png
+
+``logo-banner-dark.svg``
+------------------------
+
+.. image:: logo-banner-dark.svg
+
+A wide banner format of the logo. Embeds the words "libvirt virtualization
+API" into the basic logo graphic. The text is rendered in a dark color, so
+suitable for placement over a light background.
+
+Bitmap sizes: 256x92, 800x286 px
+
+- 256x92px:
+
+.. image:: logo-banner-dark-256.png
+
+- 800x286px:
+
+.. image:: logo-banner-dark-800.png
+
+``logo-sticker-square.svg``
+---------------------------
+
+.. image:: logo-sticker-square.svg
+
+A logo formatted into a square shape with outline, suitable for printing
+as a sticker. See https://github.com/terinjokes/StickerConstructorSpec
+
+``logo-sticker-hexagon.svg``
+----------------------------
+
+.. image:: logo-sticker-hexagon.svg
+
+A logo formatted into a hexagon shape with outline, suitable for printing
+as a sticker. See https://github.com/terinjokes/StickerConstructorSpec
+
+PNG file creation
+=================
+
+The bitmap images should not be created in Inkscape, since its anti-aliasing of
+the rendered bitmaps is too aggressive, resulting in fuzzy images. Instead the
+GIMP is used to create bitmaps as follows:
+
+ - File -> Open, select the SVG file
+
+ When prompted for the image size, enter 1024 as the width and allow height
+ to be auto-set based on aspect ratio
+
+ - Image -> Scale Image
+
+ Enter desired final bitmap size and use "Cubic" as scaling method.
+
+ - File -> Export As
+
+
+It is important to let GIMP render initially at 1024 and then scale down, rather
+than rendering directly at the target size, since this the manual scaling step
+produces better quality
diff --git a/docs/logos/meson.build b/docs/logos/meson.build
index 70ba67d71c..c65fcdd8ed 100644
--- a/docs/logos/meson.build
+++ b/docs/logos/meson.build
@@ -29,3 +29,50 @@ foreach file : docs_logo_files
install_web_files += '@0@:@1@'.format(meson.current_source_dir() / file,
docs_html_dir / 'logos')
endforeach
+
+
+html_xslt_gen_install_dir = docs_html_dir / 'logos'
+html_xslt_gen = []
+
+# README.rst is formatted as index.html for viewing
+html_xslt_gen += {
+ 'name': 'index',
+ 'file': docs_rst2html5_gen.process('README.rst'),
+ 'source': 'docs' / 'logos' / 'README.rst',
+ 'href_base': '../',
+}
+
+
+# --- begin of XSLT processing ---
+
+foreach data : html_xslt_gen
+ html_filename = data['name'] + '.html'
+
+ html_file = custom_target(
+ html_filename,
+ input: data.get('file', data['name'] + '.html.in'),
+ output: html_filename,
+ command: [
+ xsltproc_prog,
+ '--stringparam', 'pagesrc', data.get('source',
''),
+ '--stringparam', 'builddir', meson.project_build_root(),
+ '--stringparam', 'timestamp', docs_timestamp,
+ '--stringparam', 'href_base', data.get('href_base',
''),
+ '--nonet',
+ site_xsl,
+ '@INPUT@',
+ ],
+ depends: data.get('depends', []),
+ depend_files: [ page_xsl ],
+ capture: true,
+ install: true,
+ install_dir: html_xslt_gen_install_dir,
+ )
+
+ install_web_deps += html_file
+ install_web_files += html_file.full_path() + ':' + html_xslt_gen_install_dir
+endforeach
+
+html_xslt_gen = []
+
+# --- end of XSLT processing ---
--
2.39.1
5:06 a.m.
New subject: [PATCH 8/9] docs: logos: Turn 'README' into rST, generate an index and link to images
On Tue, Feb 14, 2023 at 10:51:16PM +0100, Peter Krempa wrote:
The logo directory wasn't really referenced from anywhere.
Additionally
there wasn't any reasonable index for all the image files which we have.
Turn the README file into rST and display the images it references. Link
to the new index file from the docs page.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/docs.rst | 3 +
docs/logos/README | 98 ------------------------
docs/logos/README.rst | 166 +++++++++++++++++++++++++++++++++++++++++
docs/logos/meson.build | 47 ++++++++++++
4 files changed, 216 insertions(+), 98 deletions(-)
delete mode 100644 docs/logos/README
create mode 100644 docs/logos/README.rst
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
With regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
3:51 p.m.
New subject: [PATCH 9/9] scripts: check-html-refernces: Add checking for image file usage
Check both that a file is referenced from our pages and also that pages
reference existing images.
The mode for dumping external references now also dumps images.
'--ignore-image' can be used repeatedly to suppress errors for specific
images.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
scripts/check-html-references.py | 101 ++++++++++++++++++++++++++-----
1 file changed, 87 insertions(+), 14 deletions(-)
diff --git a/scripts/check-html-references.py b/scripts/check-html-references.py
index 4f08feab59..788622a2d0 100755
--- a/scripts/check-html-references.py
+++ b/scripts/check-html-references.py
@@ -24,25 +24,32 @@ import xml.etree.ElementTree as ET
ns = {'html': 'http://www.w3.org/1999/xhtml'}
externallinks = []
+externalimages = []
def get_file_list(prefix):
filelist = []
+ imagelist = []
+ imageformats = ['.jpg', '.svg', '.png']
for root, dir, files in os.walk(prefix):
for file in files:
- if not re.search('\\.html$', file):
- continue
+ ext = os.path.splitext(file)[1]
- # the 404 page doesn't play well
- if '404.html' in file:
- continue
+ if ext == '.html':
+ # the 404 page doesn't play well
+ if '404.html' in file:
+ continue
+
+ filelist.append(os.path.join(root, file))
- filelist.append(os.path.join(root, file))
+ elif ext in imageformats:
+ imagelist.append(os.path.join(root, file))
filelist.sort()
+ imagelist.sort()
- return filelist
+ return filelist, imagelist
# loads an XHTML and extracts all anchors, local and remote links for the one file
@@ -50,12 +57,14 @@ def process_file(filename):
tree = ET.parse(filename)
root = tree.getroot()
docname = root.get('data-sourcedoc')
+ dirname = os.path.dirname(filename)
if not docname:
docname = filename
anchors = [filename]
targets = []
+ images = []
for elem in root.findall('.//html:a', ns):
target = elem.get('href')
@@ -68,7 +77,6 @@ def process_file(filename):
if re.search('://', target):
externallinks.append(target)
elif target[0] != '#' and 'mailto:' not in target:
- dirname = os.path.dirname(filename)
targetfull = os.path.normpath(os.path.join(dirname, target))
targets.append((filename, docname, targetfull, target))
@@ -87,20 +95,33 @@ def process_file(filename):
if an:
anchors.append(filename + '#' + an)
- return (anchors, targets)
+ # find local images
+ for elem in root.findall('.//html:img', ns):
+ src = elem.get('src')
+
+ if src:
+ if re.search('://', src):
+ externalimages.append(src)
+ else:
+ imagefull = os.path.normpath(os.path.join(dirname, src))
+ images.append((imagefull, docname))
+
+ return (anchors, targets, images)
def process_all(filelist):
anchors = []
targets = []
+ images = []
for file in filelist:
- anchor, target = process_file(file)
+ anchor, target, image = process_file(file)
targets = targets + target
anchors = anchors + anchor
+ images = images + image
- return (targets, anchors)
+ return (targets, anchors, images)
def check_targets(targets, anchors):
@@ -163,6 +184,46 @@ def check_usage(targets, files, entrypoint):
return fail
+# checks that images present in the directory are being used and also that
+# pages link to existing images. For favicons, which are not referenced from
+# the '.html' files there's a builtin set of exceptions.
+def check_images(usedimages, imagefiles, ignoreimages):
+ favicons = [
+ 'android-chrome-192x192.png',
+ 'android-chrome-256x256.png',
+ 'apple-touch-icon.png',
+ 'favicon-16x16.png',
+ 'favicon-32x32.png',
+ 'mstile-150x150.png',
+ ]
+ fail = False
+
+ if ignoreimages:
+ favicons = favicons + ignoreimages
+
+ for usedimage, docname in usedimages:
+ if usedimage not in imagefiles:
+ print(f'ERROR: \'{docname}\' references image
\'{usedimage}\' not among images')
+ fail = True
+
+ for imagefile in imagefiles:
+ used = False
+
+ if imagefile in (usedimage[0] for usedimage in usedimages):
+ used = True
+ else:
+ for favicon in favicons:
+ if favicon in imagefile:
+ used = True
+ break
+
+ if not used:
+ print(f'ERROR: Image \'{imagefile}\' is not used by any
page')
+ fail = True
+
+ return fail
+
+
parser = argparse.ArgumentParser(description='HTML reference checker')
parser.add_argument('--webroot', required=True,
help='path to the web root')
@@ -170,14 +231,16 @@ parser.add_argument('--entrypoint',
default="index.html",
help='file name of web entry point relative to --webroot')
parser.add_argument('--external', action="store_true",
help='print external references instead')
+parser.add_argument('--ignore-images', action='append',
+ help='paths to images that should be considered as used')
args = parser.parse_args()
-files = get_file_list(os.path.abspath(args.webroot))
+files, imagefiles = get_file_list(os.path.abspath(args.webroot))
entrypoint = os.path.join(os.path.abspath(args.webroot), args.entrypoint)
-targets, anchors = process_all(files)
+targets, anchors, usedimages = process_all(files)
fail = False
@@ -186,7 +249,14 @@ if args.external:
externallinks.sort()
for ext in externallinks:
if ext != prev:
- print(ext)
+ print(f'link: {ext}')
+
+ prev = ext
+
+ externalimages.sort()
+ for ext in externalimages:
+ if ext != prev:
+ print(f'image: {ext}')
prev = ext
else:
@@ -196,6 +266,9 @@ else:
if check_usage(targets, files, entrypoint):
fail = True
+ if check_images(usedimages, imagefiles, args.ignore_images):
+ fail = True
+
if fail:
sys.exit(1)
--
2.39.1
5:07 a.m.
New subject: [PATCH 9/9] scripts: check-html-refernces: Add checking for image file usage
On Tue, Feb 14, 2023 at 10:51:17PM +0100, Peter Krempa wrote:
Check both that a file is referenced from our pages and also that
pages
reference existing images.
The mode for dumping external references now also dumps images.
'--ignore-image' can be used repeatedly to suppress errors for specific
images.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
scripts/check-html-references.py | 101 ++++++++++++++++++++++++++-----
1 file changed, 87 insertions(+), 14 deletions(-)
Reviewed-by: Daniel P. Berrangé <berrange(a)redhat.com>
With regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
646
days inactive
647
days old
18 comments
2 participants
participants (2)
-
Daniel P. Berrangé -
Peter Krempa