From f097300c2bd980abdc485e008628aec987340990 Mon Sep 17 00:00:00 2001 From: Paul Vinciguerra Date: Tue, 24 Mar 2020 16:37:40 -0400 Subject: docs: update list of plugins The list of plugins is outdated. This change introduces a dynamically generated list of the plugins along with their descriptions, extracted directly from the sources. Type: docs Change-Id: Icb7b65e6b45289e257d71a1c18d10f62ced59cbe Signed-off-by: Paul Vinciguerra (cherry picked from commit 630ca994e0ff210a3de80d73bb395c931d2fd83f) --- docs/Makefile | 2 + docs/dynamic_includes/.gitkeep | 0 docs/gettingstarted/installing/packages.rst | 14 +----- docs/includes_renderer.py | 77 +++++++++++++++++++++++++++++ 4 files changed, 80 insertions(+), 13 deletions(-) create mode 100644 docs/dynamic_includes/.gitkeep create mode 100644 docs/includes_renderer.py (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index 6c5960d18c4..49938640a34 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -27,6 +27,8 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile +# Generate dynamic content + @python3 ./includes_renderer.py @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) spell: diff --git a/docs/dynamic_includes/.gitkeep b/docs/dynamic_includes/.gitkeep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/docs/gettingstarted/installing/packages.rst b/docs/gettingstarted/installing/packages.rst index 719fffb67f8..6c4fae18ee3 100644 --- a/docs/gettingstarted/installing/packages.rst +++ b/docs/gettingstarted/installing/packages.rst @@ -35,19 +35,7 @@ vpp-plugins Vector Packet Processing plugin modules. -* acl -* dpdk -* flowprobe -* gtpu -* ixge -* kubeproxy -* l2e -* lb -* memif -* nat -* pppoe -* sixrd -* stn +.. include:: ../../dynamic_includes/plugin_list.inc vpp-dbg ------- diff --git a/docs/includes_renderer.py b/docs/includes_renderer.py new file mode 100644 index 00000000000..d36752dd882 --- /dev/null +++ b/docs/includes_renderer.py @@ -0,0 +1,77 @@ +#!/usr/bin/env python3 +# Copyright (c) 2020. Vinci Consulting Corp. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import glob +import inspect +import os.path +import re + + +class ContentRenderer: + name = "" + curr_path = os.path.abspath(inspect.getsourcefile(lambda: 0)) + vpp_root = curr_path.rsplit("/", 2)[0] + output_dir = f"{vpp_root}/docs/dynamic_includes/" + + def render(self): + raise NotImplementedError + + +class PluginRenderer(ContentRenderer): + name = "plugin_list.inc" + + plugin_dir = f"{ContentRenderer.vpp_root}/src/plugins" + + pattern = r'VLIB_PLUGIN_REGISTER\s?\(\)\s*=\s*{.*\.description\s?=\s?"([^"]*)".*};' # noqa: 501 + regex = re.compile(pattern, re.MULTILINE | re.DOTALL) + + def render(self): + with open(f"{self.__class__.output_dir}{self.__class__.name}", + "w") as output: + with os.scandir(self.__class__.plugin_dir) as pdir: + for entry in sorted(pdir, key=lambda entry: entry.name): + if not entry.name.startswith('.') and entry.is_dir(): + description = "" + # we use glob because a plugin can (ioam for now) + # define the plugin definition in + # a further subdirectory. + for f in glob.iglob(f'{self.__class__.plugin_dir}/' + f'{entry.name}/**', + recursive=True): + if f.endswith('.c'): + with open(f, "r", encoding="utf-8") \ + as src: + for match in self.__class__.regex.finditer( + src.read()): + description = "%s" % (match.group(1)) + + output.write(f"* {entry.name} - {description}\n") + + +# if this list grows substantially, we can move the classes to +# a folder and import them. +renderers = [PluginRenderer, + ] + + +def main(): + print("rendering dynamic includes...") + for renderer in renderers: + renderer().render() + print("done.") + + +if __name__ == "__main__": + main() -- cgit 1.2.3-korg