[skip changelog] Change documentation theme to customized one

Author: silvanocerza

.github/workflows/publish-docs.yaml

@@ -82,6 +82,9 @@ jobs:
           python3 -m pip install --upgrade pip
           python3 -m pip install -r ./requirements_docs.txt
 
+      - name: Build docs theme
+        run: task docs:build-theme
+
       - name: Publish docs
         # Determine docs version for the commit pushed and publish accordingly using Mike.
         # Publishing implies creating a git commit on the gh-pages branch, we let

.gitignore

@@ -27,3 +27,4 @@ venv
 /docsgen/arduino-cli
 /docs/rpc/*.md
 /docs/commands/*.md
+/mkdocs-material

Taskfile.yml

@@ -28,12 +28,31 @@ tasks:
       - task: docs:gen:commands
       - task: docs:gen:protobuf
 
+  docs:patch-theme:
+    desc: Downloads documentation theme and patch it with custom header and footer
+    cmds:
+      - |
+        [[ -d mkdocs-material ]] && git clone https://github.com/squidfunk/mkdocs-material.git -b 5.5.14 --depth 1
+        # Ugly hack so that this doesn't fail if patch is already applied
+        git apply --check mkdocs-material-patches/*.patch && git apply mkdocs-material-patches/*.patch; echo
+
+  docs:build-theme:
+    decs: Builds documentation theme
+    dir: ./mkdocs-material
+    cmds:
+      - task: docs:patch-theme
+      - ignore_error: true
+      - npm install
+      - npm run-script build
+
   docs:build:
     desc: Build documentation website contents
     deps:
       - docs:gen:commands
       - docs:gen:protobuf
     cmds:
+      - task: docs:build-theme
+      - ignore_error: true
       - mkdocs build -s
 
   docs:publish:
@@ -62,7 +81,7 @@ tasks:
       - |
         npx -p markdown-link-check -c '
         STATUS=0
-        for file in $(find -name "*.md"); do
+        for file in $(find -path ./mkdocs-material -prune -o -name "*.md" -print); do
           markdown-link-check -c markdown-link-check-config.json -q "$file"
           STATUS=$(( $STATUS + $? ))
         done

mkdocs-material-patches/_base.scss.patch

@@ -0,0 +1,12 @@
+diff --git a/mkdocs-material/src/assets/stylesheets/main/layout/_base.scss b/mkdocs-material/src/assets/stylesheets/main/layout/_base.scss
+index 10245844..bc91241a 100644
+--- a/mkdocs-material/src/assets/stylesheets/main/layout/_base.scss
++++ b/mkdocs-material/src/assets/stylesheets/main/layout/_base.scss
+@@ -108,6 +108,7 @@ hr {
+   display: flex;
+   flex-direction: column;
+   flex-grow: 1;
++  margin-top: 8em;
+
+   // Hack: we must not use flex, or Firefox will only print the first page
+   // see https://mzl.la/39DgR3m

mkdocs-material-patches/base.html.patch

@@ -0,0 +1,61 @@
+diff --git a/mkdocs-material/src/base.html b/mkdocs-material/src/base.html
+index 9cb7ebf9..ebdcb325 100644
+--- a/mkdocs-material/src/base.html
++++ b/mkdocs-material/src/base.html
+@@ -236,7 +236,9 @@
+
+     <!-- Application header -->
+     {% block header %}
+-      {% include "partials/header.html" %}
++    <div id="arduino-header" class="temporary">
++    </div>
++      <!-- {% include "partials/header.html" %} -->
+     {% endblock %}
+
+     <!-- Container, necessary for web-application context -->
+@@ -378,20 +380,35 @@
+         {{- translations | tojson -}}
+       </script>
+
+-      <!-- Application configuration -->
+-      {% block config %}{% endblock %}
++      <!-- Custom Arduino header-footer -->
++      <link rel="stylesheet" type="text/css" href="https://cdn.arduino.cc/header-footer/prod/index.v2.css">
++      <script src="https://cdn.arduino.cc/header-footer/prod/index.v2.js"></script>
+
+-      <!-- Application initialization -->
+-      <script>
+-        app = initialize({
+-          base: "{{ base_url }}",
+-          features: {{ config.theme.features or [] | tojson }},
+-          search: Object.assign({
+-            worker: "{{ 'assets/javascripts/worker/search.js' | url }}"
+-          }, typeof search !== "undefined" && search)
++      <script type="text/javascript">
++        window.auth = new arduinoHF.CustomAuth({
++          no_auth: true
++        });
++      </script>
++
++      <script type="text/javascript">
++        // Init header
++        window.arduinoHeader = new window.arduinoHF.Header(document.getElementById('arduino-header'), window.auth, {
++            env: 'prod',
++            style: 'arduino',
++            search: {
++              tab: 'reference'
++            }
+         })
++
++        window.arduinoFooter = new window.arduinoHF.Footer(document.getElementById('arduino-footer'), {
++          env: 'prod',
++          style: 'arduino'
++        });
+       </script>
+
++      <!-- Application configuration -->
++      {% block config %}{% endblock %}
++
+       <!-- Custom JavaScript -->
+       {% for path in config["extra_javascript"] %}
+         <script src="{{ path | url }}"></script>

mkdocs-material-patches/footer.html.patch

@@ -0,0 +1,33 @@
+diff --git a/mkdocs-material/src/partials/footer.html b/mkdocs-material/src/partials/footer.html
+index 21924c41..31acf71b 100644
+--- a/mkdocs-material/src/partials/footer.html
++++ b/mkdocs-material/src/partials/footer.html
+@@ -81,27 +81,5 @@
+   {% endif %}
+
+   <!-- Further information -->
+-  <div class="md-footer-meta md-typeset">
+-    <div class="md-footer-meta__inner md-grid">
+-
+-      <!-- Copyright and theme information -->
+-      <div class="md-footer-copyright">
+-        {% if config.copyright %}
+-          <div class="md-footer-copyright__highlight">
+-            {{ config.copyright }}
+-          </div>
+-        {% endif %}
+-        Made with
+-        <a
+-          href="https://squidfunk.github.io/mkdocs-material/"
+-          target="_blank" rel="noopener"
+-        >
+-          Material for MkDocs
+-        </a>
+-      </div>
+-
+-      <!-- Social links -->
+-      {% include "partials/social.html" %}
+-    </div>
+-  </div>
++  <div id="arduino-footer"></div>
+ </footer>

mkdocs.yml

@@ -13,11 +13,18 @@ copyright: Copyright 2020 ARDUINO SA (http://www.arduino.cc/)
 
 # Theme
 theme:
-  name: material
+  name: null
+  custom_dir: mkdocs-material/material
   logo: img/icon_mac_light.png
   palette:
     primary: teal
     accent: orange
+  language: en
+  font:
+    text: Roboto
+    code: Roboto Mono
+  icon:
+    logo: logo
 
 # Extensions
 markdown_extensions:

requirements_docs.txt

@@ -1,6 +1,6 @@
 mkdocs<1.2
-mkdocs-material<5
 mike==0.5.1
 gitpython
 click<7.2
 mdx_truly_sane_lists==1.2
+pymdown-extensions>=7.0