From d1598d4274f89b9e3ad87ddb4995fa0d7919503d Mon Sep 17 00:00:00 2001
From: Paul Vinciguerra <pvinci@vinciconsulting.com>
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 <pvinci@vinciconsulting.com>
(cherry picked from commit 630ca994e0ff210a3de80d73bb395c931d2fd83f)
---
 .gitignore                                  |  1 +
 docs/Makefile                               |  2 +
 docs/dynamic_includes/.gitkeep              |  0
 docs/gettingstarted/installing/packages.rst | 14 +-----
 docs/includes_renderer.py                   | 77 +++++++++++++++++++++++++++++
 5 files changed, 81 insertions(+), 13 deletions(-)
 create mode 100644 docs/dynamic_includes/.gitkeep
 create mode 100644 docs/includes_renderer.py

diff --git a/.gitignore b/.gitignore
index ea330241549..19378e8584a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -81,6 +81,7 @@ GTAGS
 /build-root/.doxygen-bootstrap.ok
 /build-root/.doxygen-siphon.dep
 /docs/_build
+/docs/dynamic_includes
 /sphinx_venv
 !/docs/Makefile
 
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 = "<no-description-found>"
+                        # 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