Common mkdocs theme resources addition w.r.t material theme (#2)

* added theme

* adding common theme resources and build scripts

* updating the git submodule doc in read me

* updating the read me

* adding requirement.txt file for python dependencies

* removing duplicate readme file, updated license dir

* updating the readme file, mkdocs.yml and main.html

* removed ineffective line breaks

---------

Co-authored-by: Fateh Ullah <fateh.ullah@uc.se>

README.md

@@ -1,2 +1,75 @@
 # stakater-docs-mkdocs-theme
-Stakater documentation MkDocs theme
+
+This project serves as a shared MkDocs theme for all the Stakater MkDocs projects. By integrating this repository as a git submodule into your project, you can utilize the common theme and take updates.
+
+## Usage Guide
+
+### Pre-requisites
+Python 3 environment
+
+### 1. Import as git submodule
+Add the submodule to your target Mkdocs project at `theme_common` path. You can learn more about the git submodules [here](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
+
+### 2. Directory structure in target project
+Your target project directory should look like this after adding the submodule:
+```
+your-project/
+    theme_common/
+    ...
+```
+In order to override the `theme_common`, you can mirror this directory in your target project as `theme_override` and customise the files there as you need. Directory structure would look like this after that:
+```
+your-project/
+    theme_common/
+    theme_override/
+```
+In your `theme_override` folder, you can replace `mkdocs.yml` with the following starting template:
+```yaml
+site_name: <project name>
+site_url: https://project-name.stakater.com/
+repo_url: <git https url>
+docs_dir: content
+edit_uri: blob/main/content/
+
+nav:
+    - index.md
+
+```
+
+### 3. Add content in target MkDocs project
+In this project, default mkdocs documentation folder is set to `content`. If you want to override that setting, you can change following properties in `theme_override/mkdocs.yml`:
+- `docs_dir` 
+- `edit_uri`
+
+Add your content and then you can link it in `theme_override/mkdocs.yml` by overriding the following setting:
+- `nav`
+
+You can visit MkDocs official documentation to find out how to define `nav` in `mkdocs.yml` file.
+
+Target project's directory structure would look like this after adding `content` dir:
+```
+your-project/
+    theme_common/
+    theme_override/
+    content/
+```
+
+### 4. Run scripts in target project
+Assuming that target project will already have a python environment,
+execute the following commands in the root of your target project:
+1. Install Python Dependencies:
+```bash
+pip3 install -r theme_common/requirements.txt
+```
+2. Combine Theme Resources:
+```bash
+python theme_common/scripts/combine_theme_resources.py theme_common/resources theme_override/resources dist/_theme
+```
+> Above command will output combined theme to `dist/_theme`.
+3. Produce mkdocs YAML file:
+```bash
+python theme_common/scripts/combine_mkdocs_config_yaml.py theme_common/mkdocs.yml theme_override/mkdocs.yml mkdocs.yml
+```
+These scripts will create a combined theme and a `mkdocs.yml` file.
+
+Your target project will now have an mkdocs theme. If you want to customise `mkdocs.yml` or theme resources, you can do so by modifying files in `theme_override` folder and running the above scripts again.

mkdocs.yml

@@ -0,0 +1,76 @@
+site_name: Stakater Docs
+docs_dir: content
+site_url: null
+repo_url: null
+edit_uri: blob/main/content/
+use_directory_urls: false
+extra_css:
+    - stylesheets/extra.css
+theme:
+    name: material
+    font:
+      text: Montserrat
+      code: Montserrat Mono
+    custom_dir: dist/_theme
+    logo: assets/images/favicon.svg
+    favicon: assets/images/favicon.svg
+    palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        name: Switch to system preference
+        icon: material/brightness-auto
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: custom
+      accent: custom
+      toggle:
+        name: Switch to light mode
+        icon: material/brightness-7
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        name: Switch to dark mode
+        icon: material/brightness-3
+    features:
+        - content.code.copy
+        - navigation.tracking
+        - toc.follow
+        - toc.integrate
+        - navigation.top
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - attr_list
+  - pymdownx.emoji:
+        emoji_generator: !!python/name:material.extensions.emoji.to_svg
+        emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - toc:
+      permalink: "#"
+extra:
+    analytics:
+        provider: google
+        property: G-TTH1YYW5TX
+    consent:
+        title: Cookie consent
+        actions:
+            - accept
+            - reject
+            - manage
+        description: >-
+            We use cookies to recognize your repeated visits and preferences, as well
+            as to measure the effectiveness of our documentation and whether users
+            find what they're searching for. With your consent, you're helping us to
+            make our documentation better.
+    version:
+        provider: mike
+        default: latest
+plugins:
+    - search
+    - mermaid2
+    - glightbox
+
+nav:

requirements.txt

@@ -0,0 +1,3 @@
+mkdocs-material>=9.5.2,<10.0.0
+mkdocs-mermaid2-plugin>=1.1.1,<2.0.0
+mkdocs-glightbox>=0.3.5,<1.0.0

resources/404.html

@@ -0,0 +1,6 @@
+{% extends "main.html" %}
+
+{% block content %}
+  <h1>4xx - Page does not exist or has restricted access or rights</h1>
+  <p>This page does not exist or may have been deprecated or moved. Please use the search to find anything in the documentation.</p>
+{% endblock %}

resources/main.html

@@ -0,0 +1,12 @@
+{% extends "base.html" %}
+
+{% block footer %}
+<p>Copyright &copy; 2024 Stakater AB – <a href="#__consent">Change cookie settings</a></p>
+{% endblock %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}"> 
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}

resources/stylesheets/extra.css

@@ -0,0 +1,75 @@
+:root {
+    --md-primary-fg-color--light: #ECB7B7;
+    --md-primary-fg-color--dark:  #893905;
+    --md-accent-fg-color: #FF7500;
+    --md-accent-fg-color--transparent: #ffd7bd64;
+
+    /* colors for Note block */
+    .md-typeset .admonition.note, .md-typeset details.note {
+        border-color: #EF7C30;
+    }
+    .md-typeset .note>.admonition-title:before, .md-typeset .note>summary:before{
+        background-color: #EF7C30;
+    }
+
+    .md-typeset .note>.admonition-title, .md-typeset .note>summary {
+        background-color: #ef7c3030;
+    }
+    /* search results 'see more' text */
+    .md-search-result__more>summary>div {
+        color: #EF7C30;
+    }
+
+    /* font weights for headings*/
+    .md-typeset h1, .md-typeset h2, .md-typeset h3, .md-typeset h4, .md-typeset h5, .md-typeset h6 {
+        font-weight: 600;
+    }
+}
+[data-md-color-scheme="slate"] {
+    /* --md-primary-fg-color: black; */
+    --md-primary-fg-color: #EF7C30;
+    --md-default-bg-color: #131414;
+
+    --md-hue: 22;
+
+    --md-code-hl-keyword-color: #EF7C30;
+    --md-code-hl-string-color: rgba(255, 255, 255, 0.834);
+
+    /*sidebar first heading*/
+    --md-default-fg-color--light: #FFFFFF;
+    /* change Note colors using below vars */
+    /* --md-default-fg-color--lighter: #D2D8E1; */
+    /* --md-default-fg-color--lightest: #ECB7B7; */
+
+
+    .md-typeset h1, .md-typeset h2, .md-typeset h3, .md-typeset h4, .md-typeset h5, .md-typeset h6 {
+        color: #FFFFFF;
+    }
+
+    --md-typeset-color: rgba(255, 255, 255, 0.8);
+    --md-typeset-a-color: #FF7500;
+}
+
+[data-md-color-scheme="default"] {
+    /*change it to white for a white header bar*/
+    --md-primary-fg-color: #EF7C30;
+    --md-default-bg-color: white;
+
+    /*code block colors*/
+    --md-code-hl-keyword-color: #EF7C30;
+    --md-code-hl-string-color: rgba(0, 0, 0, 0.7);
+
+    /*sidebar heading title*/
+    --md-default-fg-color--light: rgba(0, 0, 0, 0.837);
+    /*default heading color*/
+    .md-typeset h1, .md-typeset h2, .md-typeset h3, .md-typeset h4, .md-typeset h5, .md-typeset h6 {
+        color: rgba(0, 0, 0, 0.837);
+    }
+    /*to change the header bar text to black*/
+    /* .md-header {
+        color: black;
+    } */
+
+    --md-typeset-color: rgba(0, 0, 0, 0.8);
+    --md-typeset-a-color: #EF7C30;
+}

scripts/combine_mkdocs_config_yaml.py

@@ -0,0 +1,34 @@
+import yaml
+import sys
+
+def merge_yaml_files(file1, file2, output_file):
+
+    with open(file1, 'r') as f1, open(file2, 'r') as f2:
+        # data1 = yaml.safe_load(f1)
+        # data2 = yaml.safe_load(f2)
+        data1 = yaml.load(f1, Loader=yaml.Loader)
+        data2 = yaml.load(f2, Loader=yaml.Loader)
+        merged_data = merge_dicts(data1, data2)
+
+    with open(output_file, 'w') as out_file:
+        yaml.dump(merged_data, out_file, default_flow_style=False)
+
+def merge_dicts(dict1, dict2):
+    for key, value in dict2.items():
+        if key in dict1 and isinstance(dict1[key], dict) and isinstance(value, dict):
+            dict1[key] = merge_dicts(dict1[key], value)
+        else:
+            dict1[key] = value
+    return dict1
+
+if __name__ == "__main__":
+
+    if len(sys.argv) != 4:
+        print("Usage: python combine_mkdocs_config_yaml.py <common_mkdocs_file_path> <override_mkdocs_file_path> <output_path>")
+        sys.exit(1)
+    common_mkdocs_file_path = sys.argv[1]
+    override_mkdocs_file_path = sys.argv[2]
+    output_path = sys.argv[3]
+
+    merge_yaml_files(common_mkdocs_file_path, override_mkdocs_file_path, output_path)
+    print(f"YAML files merged successfully. Merged file saved at {output_path}")

scripts/combine_theme_resources.py

@@ -0,0 +1,31 @@
+import shutil
+import os
+import sys
+
+def copy_submodule(source_dir, destination_dir):
+    if os.path.exists(destination_dir):
+        shutil.rmtree(destination_dir)
+    shutil.copytree(source_dir, destination_dir)
+    print("Submodule copied to destination.")
+
+def override_resources(theme_override_dir, output_to_dir):
+    source_override_dir = theme_override_dir
+    destination_override_dir = output_to_dir
+    for item in os.listdir(source_override_dir):
+        s = os.path.join(source_override_dir, item)
+        d = os.path.join(destination_override_dir, item)
+        if os.path.isdir(s):
+            shutil.copytree(s, d, dirs_exist_ok=True)
+        else:
+            shutil.copy2(s, d)
+    print("Resources overridden.")
+
+if __name__ == "__main__":
+    if len(sys.argv) != 4:
+        print("Usage: python combine_theme_resources.py <source_dir_path> <override_from_dir_path> <output_dir_path>")
+        sys.exit(1)
+    source_dir_path = sys.argv[1]
+    overridefrom_dir_path = sys.argv[2]
+    output_dir_path = sys.argv[3]
+    copy_submodule(source_dir_path,output_dir_path)
+    override_resources(overridefrom_dir_path, output_dir_path)