Add search field in 'webviz docs' docs (#283)

equinor · Sep 18, 2020 · 1e5b676 · 1e5b676
1 parent 623ab6f
commit 1e5b676
Show file tree

Hide file tree

Showing 7 changed files with 53 additions and 20 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased] - YYYY-MM-DD
 ### Added
+- [#283](https://github.com/equinor/webviz-config/pull/283) - Auto-generated Webviz plugin documentation
+now has search functionality (using [`docsify` full text search](https://docsify.js.org/#/plugins?id=full-text-search)).
 - [#278](https://github.com/equinor/webviz-config/pull/278) - Plugin authors can now use Dash inline callbacks
 (i.e. `app.clientside_callback(...)`) without being in conflict with the strict
 [CSP rules](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)

diff --git a/package.json b/package.json
@@ -2,7 +2,7 @@
   "name": "webviz-config",
   "description": "Documentation system for webviz-config plugins",
   "scripts": {
-    "postinstall": "cd ./node_modules; cp ./docsify/lib/docsify.min.js ./docsify/lib/themes/vue.css ./docsify-tabs/dist/docsify-tabs.min.js ./prismjs/components/prism-bash.min.js ./prismjs/components/prism-python.min.js ./prismjs/components/prism-yaml.min.js ./docsify-copy-code/dist/docsify-copy-code.min.js ./katex/dist/katex.min.css ./docsify-katex/dist/docsify-katex.js ../INTRODUCTION.md ../webviz_config/_docs/static/; mkdir -p ../webviz_config/_docs/static/fonts; cp ./katex/dist/fonts/*.woff2 ../webviz_config/_docs/static/fonts/; cd .."
+    "postinstall": "cd ./node_modules; cp ./docsify/lib/docsify.min.js ./docsify/lib/plugins/search.min.js ./docsify/lib/themes/vue.css ./docsify-tabs/dist/docsify-tabs.min.js ./prismjs/components/prism-bash.min.js ./prismjs/components/prism-python.min.js ./prismjs/components/prism-yaml.min.js ./docsify-copy-code/dist/docsify-copy-code.min.js ./katex/dist/katex.min.css ./docsify-katex/dist/docsify-katex.js ../INTRODUCTION.md ../webviz_config/_docs/static/; mkdir -p ../webviz_config/_docs/static/fonts; cp ./katex/dist/fonts/*.woff2 ../webviz_config/_docs/static/fonts/; cd .."
   },
   "author": "Equinor",
   "license": "MIT",

diff --git a/webviz_config/_docs/_build_docs.py b/webviz_config/_docs/_build_docs.py
@@ -152,6 +152,19 @@ def build_docs(build_directory: pathlib.Path) -> None:
         build_directory,
     )
 
+    # While waiting for https://github.com/jhildenbiddle/docsify-tabs/pull/30
+    # to be reviewed, merged and released:
+    substring_prefix = (
+        r"/[\r\n]*(\s*)<!-+\s+tab:\s*(.*)\s+-+>[\r\n]+([\s\S]*?)[\r\n]*\s*"
+    )
+    docsify_tabs_file = build_directory / "docsify-tabs.min.js"
+    docsify_tabs_file.write_text(
+        docsify_tabs_file.read_text().replace(
+            substring_prefix + r"(?=<!-+\s+tabs?:)/m",
+            substring_prefix + r"(?=<!-+\s+(tab:\s*(.*)|tabs:\s*?end)\s+-+>)/m",
+        )
+    )
+
     template_environment = jinja2.Environment(  # nosec
         loader=jinja2.PackageLoader("webviz_config", "templates"),
         undefined=jinja2.StrictUndefined,
@@ -162,7 +175,7 @@ def build_docs(build_directory: pathlib.Path) -> None:
 
     template = template_environment.get_template("README.md.jinja2")
     for package_name, package_doc in plugin_documentation.items():
-        (build_directory / (package_name + ".md")).write_text(
+        (build_directory / f"{package_name}.md").write_text(
             template.render({"package_name": package_name, "package_doc": package_doc})
         )
 
@@ -171,6 +184,16 @@ def build_docs(build_directory: pathlib.Path) -> None:
         template.render({"packages": plugin_documentation.keys()})
     )
 
+    template = template_environment.get_template("webviz-doc.js.jinja2")
+    (build_directory / "webviz-doc.js").write_text(
+        template.render(
+            {
+                "paths": ["/"]
+                + [f"/{package_name}" for package_name in plugin_documentation]
+            }
+        )
+    )
+
 
 def _split_docstring(docstring: str) -> List[str]:
     """Divides docstring by splitting on ---, also unindents

diff --git a/webviz_config/_docs/static/index.html b/webviz_config/_docs/static/index.html
@@ -19,6 +19,7 @@
       <script src="./prism-bash.min.js"></script>
       <script src="./prism-python.min.js"></script>
       <script src="./prism-yaml.min.js"></script>
-    </body>
+      <script src="./search.min.js"></script>
+   </body>
 </html>
 
diff --git a/webviz_config/_docs/static/webviz-doc.js b/webviz_config/_docs/static/webviz-doc.js
diff --git a/webviz_config/templates/README.md.jinja2 b/webviz_config/templates/README.md.jinja2
@@ -17,13 +17,13 @@
 <!-- tabs:start -->
 {% if plugin["description"] is not none %}   
 
-#### ** Description **
+<!-- tab:Description -->
 
 {{ plugin["description"] }}
 
 {% endif %} 
 
-#### ** Arguments **
+<!-- tab:Arguments -->
 
 {% if plugin["argument_description"] is not none %}   
 {{ plugin["argument_description"] }}
@@ -38,7 +38,7 @@
 
 {% if plugin["data_input"] is not none %}   
 
-#### ** Data input **
+<!-- tab:Data input -->
 
 {{ plugin["data_input"] }}
 

diff --git a/webviz_config/templates/webviz-doc.js.jinja2 b/webviz_config/templates/webviz-doc.js.jinja2
@@ -0,0 +1,21 @@
+window.$docsify = {
+    logo: "./webviz-logo.svg",
+    homepage: "INTRODUCTION.md",    
+    name: "Webviz",
+    loadSidebar: "sidebar.md",
+    subMaxLevel: 4,
+    copyCode: {
+        buttonText : "Copy",
+    },
+    tabs: {
+        sync: false,
+        theme: "material",
+        tabHeadings: false
+    },
+    search: {
+        paths: {{ paths | tojson }},
+        depth: 6,
+        hideOtherSidebarContent: true,
+        maxAge: 30e3 // default cache maxage one day (8.64e7 ms) - old cached content can be confusing if user changes installed webviz plugins
+    }
+}