Add chart with translation coverage

[terual]

By using the data in strings.txt and mkdocs-charts-plugin we can dynamically create a chart which shows the coverage of the translations of the different languages.

But I am not sure if we want to use "community" plugins for mkdocs.

[terual]

I wanted to attach a screenshot of the chart, but Github isn't allowing me today....

[michaelherger]

Trying to run this branch I'm getting the following error:

Error: MkDocs encountered an error parsing the configuration file: while constructing a Python object
cannot find module 'mkdocs_charts_plugin.fences' (No module named 'mkdocs_charts_plugin')
  in "/docs/mkdocs.yml", line 83, column 19

[terual]

Yeah, it needs a plugin:

pip install mkdocs-charts-plugin

But to add this plugin to the docker image you need to build an image yourself, see https://squidfunk.github.io/mkdocs-material/getting-started/#with-docker. That's also why I am a bit hesitant.

[michaelherger]

Thanks, got it! There's a Dockerfile for this:

diff --git a/Dockerfile b/Dockerfile
index 2889c80..736d074 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,2 +1,3 @@
 FROM squidfunk/mkdocs-material:latest
-RUN pip install mkdocs-macros-plugin
\ No newline at end of file
+RUN pip install mkdocs-macros-plugin
+RUN pip install mkdocs-charts-plugin

[michaelherger]

Nice one! Here's how it looks after a few tweaks:

I needed to change the initialization:

diff --git a/mkdocs.yml b/mkdocs.yml
index b4d89ac..74ca3a9 100755
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -43,7 +43,7 @@ theme:

 plugins:
   - search
-  - privacy
+  # - privacy
   - macros:
       include_yaml:
         - docs/getting-started/downloads.yaml
@@ -68,7 +68,11 @@ extra:
 markdown_extensions:
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: vegalite
+          class: vegalite
+          format: !!python/name:mkdocs_charts_plugin.fences.fence_vegalite
   - pymdownx.tabbed:
       alternate_style: true
   - attr_list
@@ -76,11 +80,6 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
-  - pymdownx.superfences:
-      custom_fences:
-        - name: vegalite
-          class: vegalite
-          format: !!python/name:mkdocs_charts_plugin.fences.fence_vegalite

 nav:
   - Home:

I'm sure there's a fix for the privacy flag (which I really want to enable!).

That said: wouldn't the same be possible using Mermaid, which MkDocs/Material supports out of the box?

https://squidfunk.github.io/mkdocs-material/reference/diagrams/

[terual]

Unfortunately Mermaid.js does not support bar charts... I have found a hack to use the Gantt chart for a bar chart, but it's far from elegant.

BTW, with privacy enabled the chart works after one (or two) refreshes. So there is something funny going on.

[michaelherger]

What about Mermaid's "XY Chart"?

https://mermaid.js.org/syntax/xyChart.html

[terual]

You can create something usable:

xychart-beta
    x-axis [English, German, French, Dutch, Hebrew]
    y-axis "Coverage in %" 0 --> 100
    bar [100, 80, 70, 65, 55]

But I haven't found a possibility to use external data...

[terual]

Another option is to just display the data in a table, and leave the fancy graphics for the future.

[michaelherger]

Mind to share the Mermaid code you used to do that? Maybe the macros could be used: the script would store the data to YAML, which the macros plugin would insert on the page?

Edit: I can't get Mermaid to work at all. Might be a Docker problem: the browser is trying to get the library (and only Mermaid!) from http://0.0.0.0 instead of localhost and fails to load it.

Edit2: removing the privacy flag worked around this. Seems to be a Docker issue indeed.

[michaelherger]

Here's what a quick test came up with:

Code on page:

## Current coverage of translations

The data below can be skewed towards English, as there's no need to define terms for your languages when the translations is identical to the English version.

```  mermaid
xychart-beta
    title "Translations"
    x-axis [{{ translationLabels }}]
    y-axis "Coverage in %" 0 --> 100
    bar [{{ translationCoverage }}]

The data would have to be stored in YAML instead of JSON:
```yaml
---
translationLabels: "CS, DA, DE, EN, EN_GB, ES, FI, FR, HE, IT, JA, NL, NO, PL, PT, RU, SV, ZH_CN"
translationCoverage: "97.35973597359735, 92.14521452145215, 99.00990099009901, 100.0, 2.6402640264026402, 92.87128712871286, 91.61716171617162, 99.8019801980198, 50.2970297029703, 91.74917491749174, 31.94719471947195, 99.14191419141915, 95.18151815181518, 95.18151815181518, 23.762376237623762, 91.2871287128713, 97.55775577557756, 57.755775577557756"

Then include this YAML file with the macros plugin:

diff --git a/mkdocs.yml b/mkdocs.yml
index f3ca36b..2dc97ad 100755
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -43,11 +43,12 @@ theme:

 plugins:
   - search
   - privacy
   - macros:
       include_yaml:
         - docs/getting-started/downloads.yaml
         - docs/players-and-controllers/firmware-versions.yaml
+        - docs/contributing/strings-coverage.yaml

 extra:
   social:
@@ -62,7 +63,11 @@ extra:
 markdown_extensions:
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.tabbed:
       alternate_style: true
   - attr_list

[terual]

Thanks!! Adjusting the Python script to output yaml is easy enough, will do that as soon as I find some time.

[terual]

Done! It looks reasonably good. Only downside is that is doesn't change color using dark mode.

[michaelherger]

I think that's a great start. Please click "Ready for review" if you think we can merge this.

[terual]

Nice, and the script works first time :) https://github.com/LMS-Community/lms-community.github.io/commit/8fbc7b4000d9f93a821d1abe790d01e5ab2206de