From: Vladimír Vondruš Date: Mon, 4 Jun 2018 07:21:40 +0000 (+0200) Subject: plugins: new m.vk plugin. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=9d946a6c47c99b24b5f0112621400be39ff10d0c;p=blog.git plugins: new m.vk plugin. --- diff --git a/doc/plugins.rst b/doc/plugins.rst index afb54bbd..9a4de1ef 100644 --- a/doc/plugins.rst +++ b/doc/plugins.rst @@ -49,6 +49,7 @@ and restart Pelican. Download the plugins below or - :gh:`m.gh `, :gh:`m.dox `, :gh:`m.gl `, + :gh:`m.vk `, :gh:`m.abbr `, :gh:`m.filesize `, :gh:`m.alias ` @@ -97,10 +98,10 @@ as an inline SVG and can be styled using CSS like everything else. `Links and other » <{filename}/plugins/links.rst>`_ =================================================== -The :py:`m.gh`, :py:`m.dox`, :py:`m.gl`, :py:`m.abbr`, :py:`m.fiilesize` and -:py:`m.alias` plugins make it easy for you to link to GitHub projects, issues -or PRs, to Doxygen documentation, query file sizes and provide URL aliases to -preserve link compatibility. +The :py:`m.gh`, :py:`m.dox`, :py:`m.gl`, :py:`m.vk`, :py:`m.abbr`, +:py:`m.fiilesize` and :py:`m.alias` plugins make it easy for you to link to +GitHub projects, issues or PRs, to Doxygen documentation, query file sizes and +provide URL aliases to preserve link compatibility. `Metadata » <{filename}/plugins/metadata.rst>`_ =============================================== diff --git a/doc/plugins/links.rst b/doc/plugins/links.rst index eb57a94d..6ee44000 100644 --- a/doc/plugins/links.rst +++ b/doc/plugins/links.rst @@ -137,6 +137,43 @@ well-known syntax. - Extension function link: :glfnext:`SpecializeShader ` - :glfn:`Custom link title ` +`Vulkan functions and extensions`_ +================================== + +Download the `m/vk.py <{filename}/plugins.rst>`_ file, put it +including the ``m/`` directory into one of your :py:`PLUGIN_PATHS` and add +:py:`m.vk` package to your :py:`PLUGINS` in ``pelicanconf.py``: + +.. code:: python + + PLUGINS += ['m.vk'] + +Use the :rst:`:vkfn:` interpreted text role for linking to functions, +:rst:`:vktype:` for linking to types and :rst:`:vkext:` for linking to +extensions. In the link target the leading ``vk`` prefix of functions, ``Vk`` +prefix of types and the leading ``VK_`` prefix of extensions is prepended +automatically. + +Link text is equal to full function name including the ``vk`` prefix and +``()`` for functions, ``Vk`` prefix for types or equal to extension name. It's +possible to specify alternate link text using the well-known syntax. + +.. code-figure:: + + .. code:: rst + + - Function link: :vkfn:`CreateInstance` + - Type link: :vktype:`InstanceCreateInfo` + - Definition link: :vktype:`VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO ` + - Extension link: :vkext:`KHR_swapchain` + - :vkfn:`Custom link title ` + + - Function link: :vkfn:`CreateInstance` + - Type link: :vktype:`InstanceCreateInfo` + - Definition link: :vktype:`VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO ` + - Extension link: :vkext:`KHR_swapchain` + - :vkfn:`Custom link title ` + `Doxygen documentation`_ ======================== diff --git a/pelican-plugins/m/abbr.py b/pelican-plugins/m/abbr.py index 4eb705e1..219f9dcb 100644 --- a/pelican-plugins/m/abbr.py +++ b/pelican-plugins/m/abbr.py @@ -27,7 +27,7 @@ from docutils import nodes, utils from docutils.parsers import rst # to avoid dependencies, link_regexp and parse_link() is common for m.abbr, -# m.gh and m.gl +# m.gh, m.gl and m.vk link_regexp = re.compile(r'(?P.*) <(?P<link>.+)>') diff --git a/pelican-plugins/m/gh.py b/pelican-plugins/m/gh.py index 422d12de..689a55ab 100644 --- a/pelican-plugins/m/gh.py +++ b/pelican-plugins/m/gh.py @@ -27,7 +27,7 @@ from docutils import nodes, utils from docutils.parsers import rst # to avoid dependencies, link_regexp and parse_link() is common for m.abbr, -# m.gh and m.gl +# m.gh, m.gl and m.vk link_regexp = re.compile(r'(?P<title>.*) <(?P<link>.+)>') diff --git a/pelican-plugins/m/gl.py b/pelican-plugins/m/gl.py index ae61867d..01f9b84c 100644 --- a/pelican-plugins/m/gl.py +++ b/pelican-plugins/m/gl.py @@ -27,7 +27,7 @@ from docutils import nodes, utils from docutils.parsers import rst # to avoid dependencies, link_regexp and parse_link() is common for m.abbr, -# m.gh and m.gl +# m.gh, m.gl and m.vk link_regexp = re.compile(r'(?P<title>.*) <(?P<link>.+)>') diff --git a/pelican-plugins/m/test/test_vk.py b/pelican-plugins/m/test/test_vk.py new file mode 100644 index 00000000..56ca17fd --- /dev/null +++ b/pelican-plugins/m/test/test_vk.py @@ -0,0 +1,36 @@ +# +# This file is part of m.css. +# +# Copyright © 2017, 2018 Vladimír VondruÅ¡ <mosra@centrum.cz> +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +# DEALINGS IN THE SOFTWARE. +# + +from m.test import PluginTestCase + +class Vk(PluginTestCase): + def __init__(self, *args, **kwargs): + super().__init__(__file__, '', *args, **kwargs) + + def test(self): + self.run_pelican({ + 'PLUGINS': ['m.htmlsanity', 'm.vk'] + }) + + self.assertEqual(*self.actual_expected_contents('page.html')) diff --git a/pelican-plugins/m/test/vk/page.html b/pelican-plugins/m/test/vk/page.html new file mode 100644 index 00000000..b5003d3a --- /dev/null +++ b/pelican-plugins/m/test/vk/page.html @@ -0,0 +1,40 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8" /> + <title>m.vk | A Pelican Blog + + + + + + +
+
+ +
+ + diff --git a/pelican-plugins/m/test/vk/page.rst b/pelican-plugins/m/test/vk/page.rst new file mode 100644 index 00000000..2bc76cdd --- /dev/null +++ b/pelican-plugins/m/test/vk/page.rst @@ -0,0 +1,8 @@ +m.vk +#### + +- Function link: :vkfn:`CreateInstance` +- Type link: :vktype:`InstanceCreateInfo` +- Definition link: :vktype:`VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO ` +- Extension link: :vkext:`KHR_swapchain` +- :vkfn:`Custom link title ` diff --git a/pelican-plugins/m/vk.py b/pelican-plugins/m/vk.py new file mode 100644 index 00000000..7eba3d6d --- /dev/null +++ b/pelican-plugins/m/vk.py @@ -0,0 +1,64 @@ +# +# This file is part of m.css. +# +# Copyright © 2017, 2018 Vladimír Vondruš +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +# DEALINGS IN THE SOFTWARE. +# + +import re +from docutils import nodes, utils +from docutils.parsers import rst + +# to avoid dependencies, link_regexp and parse_link() is common for m.abbr, +# m.gh, m.gl and m.vk + +link_regexp = re.compile(r'(?P.*) <(?P<link>.+)>') + +def parse_link(text): + link = utils.unescape(text) + m = link_regexp.match(link) + if m: return m.group('title', 'link') + return None, link + +def vkext(name, rawtext, text, lineno, inliner, options={}, content=[]): + title, extension = parse_link(text) + if not title: title = extension + url = "https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_{}".format(extension) + node = nodes.reference(rawtext, title, refuri=url, **options) + return [node], [] + +def vkfn(name, rawtext, text, lineno, inliner, options={}, content=[]): + title, fn = parse_link(text) + if not title: title = "vk{}()".format(fn) + url = "https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vk{}.html".format(fn) + node = nodes.reference(rawtext, title, refuri=url, **options) + return [node], [] + +def vktype(name, rawtext, text, lineno, inliner, options={}, content=[]): + title, fn = parse_link(text) + if not title: title = "Vk{}".format(fn) + url = "https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/Vk{}.html".format(fn) + node = nodes.reference(rawtext, title, refuri=url, **options) + return [node], [] + +def register(): + rst.roles.register_local_role('vkext', vkext) + rst.roles.register_local_role('vkfn', vkfn) + rst.roles.register_local_role('vktype', vktype) diff --git a/site/pelicanconf.py b/site/pelicanconf.py index 55b845bd..5493bdc7 100644 --- a/site/pelicanconf.py +++ b/site/pelicanconf.py @@ -148,7 +148,8 @@ PLUGINS = ['m.abbr', 'm.images', 'm.math', 'm.metadata', - 'm.plots'] + 'm.plots', + 'm.vk'] THEME = '../pelican-theme' THEME_STATIC_DIR = 'static'