docs: support json builder for cheatsheet (#3132)

Co-authored-by: Mohammad Alisafaee <[email protected]>

Author: Panaetius

.github/workflows/cheatsheet.yml

@@ -0,0 +1,97 @@
+name: Create cheatsheet
+
+on:
+  push:
+    branches:
+      - "**"
+    tags:
+      - "v*.*.*"
+env:
+  DEPENDENCY_CACHE_PREFIX: "v2"
+  NETWORK_CACHE_PREFIX: "v1"
+jobs:
+  cheatsheet:
+    runs-on: ubuntu-latest
+    if: "'refs/heads/master' != github.ref && 'refs/heads/develop' != github.ref && !startsWith(github.ref, 'refs/tags/')"
+    steps:
+      - uses: actions/checkout@v2
+      - run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.9
+      - name: Install xetex
+        run: |
+          sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu jammy main restricted multiverse universe"
+          sudo apt-get update -y
+          sudo apt-get install -y -t jammy texlive-xetex
+
+      - uses: actions/cache@master
+        id: cache
+        with:
+          path: |
+            ${{ env.pythonLocation }}
+            renku/templates
+          key: ${{env.CACHE_PREFIX}}-${{ runner.os }}-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{hashFiles('poetry.lock')}}-${{hashFiles('build.py')}}
+      - name: Install dependencies
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install coveralls poetry wheel twine poetry-dynamic-versioning==0.17.1
+          poetry-dynamic-versioning
+          python -m pip install .[all]
+      - name: Install renku into cache
+        if: steps.cache.outputs.cache-hit == 'true'
+        run: |
+          poetry-dynamic-versioning
+          python -m pip install --no-deps .
+      - name: Set Git config
+        run: |
+          git config --global --add user.name "Renku Bot"
+          git config --global --add user.email "[email protected]"
+      - name: Build cheatsheet
+        run: |
+          sphinx-build -b latex -c docs/cheatsheet/ docs docs/latex/ -W
+          cd docs/latex/
+          xelatex cheatsheet
+          cat <(md5sum cheatsheet.tex) <(md5sum sdsc_cheatsheet.cls) > ../cheatsheet_hash_new
+          cd ../..
+        env:
+          CHEATSHEET_TARGET: rp
+      - name: Build cheatsheet json
+        run: |
+          sphinx-build -b json -c docs/cheatsheet/ docs docs/json/ -W
+          cd docs/json/
+          python -c 'import json; print(json.dumps(json.loads(json.load(open("cheatsheet.fjson", "r"))["body"]), indent=2, sort_keys=True))' > cheatsheet.json
+          cat <(md5sum cheatsheet.json) > ../cheatsheet_json_hash_new
+          cd ../..
+      - name: Publish cheatsheet if changed
+        id: publish
+        if: ${{ hashFiles('docs/cheatsheet_hash') != hashFiles('docs/cheatsheet_hash_new') }}
+        run: |
+          cat docs/cheatsheet_hash
+          cat docs/cheatsheet_hash_new
+          cd docs
+          rm cheatsheet_hash
+          mv cheatsheet_hash_new cheatsheet_hash
+          cp latex/cheatsheet.pdf _static/cheatsheet/
+          git add cheatsheet_hash _static/cheatsheet/cheatsheet.pdf
+          git commit -m "chore: Update cheatsheet pdf"
+      - name: Publish UI cheatsheet if changed
+        id: publish
+        if: ${{ hashFiles('docs/cheatsheet_json_hash') != hashFiles('docs/cheatsheet_json_hash_new') }}
+        run: |
+          cat docs/cheatsheet_json_hash
+          cat docs/cheatsheet_json_hash_new
+          cd docs
+          rm cheatsheet_json_hash
+          mv cheatsheet_json_hash_new cheatsheet_json_hash
+          cp json/cheatsheet.json _static/cheatsheet/
+          git add cheatsheet_json_hash _static/cheatsheet/cheatsheet.json
+          git commit -m "chore: Update cheatsheet json"
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        if: steps.publish.outcome != 'Skipped' && success()
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ github.ref }}

.github/workflows/test_deploy.yml

@@ -170,71 +170,6 @@ jobs:
           POETRY_VIRTUALENVS_CREATE: false
         run: mypy
 
-  cheatsheet:
-    runs-on: ubuntu-latest
-    if: "'refs/heads/master' != github.ref && 'refs/heads/develop' != github.ref && !startsWith(github.ref, 'refs/tags/')"
-    steps:
-      - uses: actions/checkout@v3
-      - run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
-      - name: Set up Python 3.7
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.9
-      - name: Install xetex
-        run: |
-          sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu jammy main restricted multiverse universe"
-          sudo apt-get update -y
-          sudo apt-get install -y -t jammy texlive-xetex
-
-      - uses: actions/cache@master
-        id: cache
-        with:
-          path: |
-            ${{ env.pythonLocation }}
-            renku/templates
-          key: ${{env.CACHE_PREFIX}}-${{ runner.os }}-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{hashFiles('poetry.lock')}}-${{hashFiles('build.py')}}
-      - name: Install dependencies
-        if: steps.cache.outputs.cache-hit != 'true'
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install coveralls poetry wheel twine poetry-dynamic-versioning==0.17.1
-          poetry-dynamic-versioning
-          python -m pip install .[all]
-      - name: Install renku into cache
-        if: steps.cache.outputs.cache-hit == 'true'
-        run: |
-          poetry-dynamic-versioning
-          python -m pip install --no-deps .
-      - name: Set Git config
-        run: |
-          git config --global --add user.name "Renku Bot"
-          git config --global --add user.email "[email protected]"
-      - name: Build cheatsheet
-        run: |
-          sphinx-build -b latex -c docs/cheatsheet/ docs docs/latex/ -W
-          cd docs/latex/
-          xelatex cheatsheet
-          cat <(md5sum cheatsheet.tex) <(md5sum sdsc_cheatsheet.cls) > ../cheatsheet_hash_new
-          cd ../..
-      - name: Publish cheatsheet if changed
-        id: publish
-        if: ${{ hashFiles('docs/cheatsheet_hash') != hashFiles('docs/cheatsheet_hash_new') }}
-        run: |
-          cat docs/cheatsheet_hash
-          cat docs/cheatsheet_hash_new
-          cd docs
-          rm cheatsheet_hash
-          mv cheatsheet_hash_new cheatsheet_hash
-          cp latex/cheatsheet.pdf _static/cheatsheet/
-          git add cheatsheet_hash _static/cheatsheet/cheatsheet.pdf
-          git commit -m "chore: Update cheatsheet"
-      - name: Push changes
-        uses: ad-m/github-push-action@master
-        if: steps.publish.outcome != 'Skipped' && success()
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          branch: ${{ github.ref }}
-
   test-distro:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -68,6 +68,8 @@ renku.err
 docs/_build/
 docs/.doctrees/
 docs/_sidebar.rst.inc
+docs/latex/
+docs/json/
 _sidebar.rst.inc
 
 # PyBuilder

docs/_ext/cheatsheet.py

@@ -1,8 +1,27 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2018-2022- Swiss Data Science Center (SDSC)
+# A partnership between École Polytechnique Fédérale de Lausanne (EPFL) and
+# Eidgenössische Technische Hochschule Zürich (ETHZ).
+#
+# 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.
+"""Sphinx extension to handle cheatsheet entries."""
+
+import json
 from collections import defaultdict
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
-from sphinx.locale import _
 from sphinx.util import texescape
 from sphinx.util.docutils import SphinxDirective
 
@@ -17,6 +36,17 @@ def add_linebreaks(text, breakstring=" \\linebreak "):
     return text.replace("\n", " ").replace("|||", breakstring)
 
 
+def list_directive(argument):
+    """A docutils directive to take a list of values."""
+    if argument is not None:
+        argument = argument.strip()
+
+    if not argument:
+        raise ValueError("argument required but none supplied")
+
+    return [a.strip() for a in argument.split(",")]
+
+
 class cheatsheet_list(nodes.General, nodes.Element):
     """Sphinx element to output a list of cheatsheet entries."""
 
@@ -40,7 +70,7 @@ class CheatsheetDirective(SphinxDirective):
         "command": directives.unchanged_required,
         "description": directives.unchanged_required,
         "group": directives.unchanged_required,
-        "extended": directives.flag,
+        "target": list_directive,
     }
 
     def run(self):
@@ -52,6 +82,7 @@ def run(self):
         command = self.options.get("command")
         description = self.options.get("description")
         group = self.options.get("group")
+        target = self.options.get("target")
 
         if any(
             command == e["command"] and description == e["description"] and group == e["group"]
@@ -64,7 +95,7 @@ def run(self):
                 "command": command,
                 "description": description,
                 "group": group,
-                "extended": True if "extended" in self.options else False,
+                "target": target,
                 "docname": self.env.docname,
             }
         )
@@ -103,6 +134,23 @@ def process_latex_entries(content, entries, groups):
             content.append(nodes.raw("", f"\commandsubsection{{{command}}}{{{description}}}", format="latex"))
 
 
+def process_json_entries(content, entries, groups):
+    """Create output when building json cheatsheet."""
+    data = {"groups": []}
+    for group in groups:
+        entry_list = entries[group]
+        group_entry = {"name": group, "commands": []}
+
+        for entry in entry_list:
+            group_entry["commands"].append(
+                {"command": entry["command"], "description": entry["description"], "target": entry["target"]}
+            )
+
+        data["groups"].append(group_entry)
+
+    content.append(nodes.raw("", json.dumps(data), format="html"))
+
+
 def process_regular_entries(content, entries, groups):
     """Create output when building regular (html) cheatsheet."""
     for group in groups:
@@ -142,11 +190,13 @@ def process_cheatsheet_nodes(app, doctree, fromdocname):
         entries = defaultdict(list)
 
         for cheatsheet_info in env.cheatsheet_all_entries:
-            if not cheatsheet_info["extended"] or app.config.cheatsheet_extended:
+            if not app.config.cheatsheet_target or app.config.cheatsheet_target in cheatsheet_info["target"]:
                 entries[cheatsheet_info["group"]].append(cheatsheet_info)
 
         if app.builder.name == "latex":
             process_latex_entries(content, entries, app.config.cheatsheet_groups)
+        elif app.builder.name == "json":
+            process_json_entries(content, entries, app.config.cheatsheet_groups)
         else:
             process_regular_entries(content, entries, app.config.cheatsheet_groups)
 
@@ -156,7 +206,7 @@ def process_cheatsheet_nodes(app, doctree, fromdocname):
 def setup(app):
     """Run setup method for directive/plugin."""
 
-    app.add_config_value("cheatsheet_extended", False, "html")
+    app.add_config_value("cheatsheet_target", None, "html")
     app.add_config_value("cheatsheet_groups", [], "html")
     app.add_node(cheatsheet_list)