Documentation Update. (#216)

* Reworked the Documentation.

* Updated pipeline.

.github/workflows/documentation.yml

@@ -54,7 +54,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: pip install mkdocs mkdocs-mermaid2-plugin
+      - run: pip install mkdocs mkdocs-material mkdocs-minify-plugin
       - run: |
           cd docs
           mkdocs gh-deploy --force --clean --verbose

docs/.gitignore

@@ -0,0 +1 @@
+.venv

docs/mkdocs.yml

@@ -1,33 +1,120 @@
+# Project information
 site_name: OSDU Developer
 site_author: Microsoft Azure Energy
+site_name: OSDU Developer
+site_url: https://azure.github.io/osdu-developer/
+site_author: Daniel Scholl
+site_description: >-
+  OSDU Developer - Personal Instances : Simplified
+
 docs_dir: src
 
-theme: readthedocs
+# Repository
+repo_name: azure/osdu-developer
+repo_url: https://github.com/azure/osdu-developer
 
-extra_css:
-  - css/override.css
+# Copyright
+copyright: Copyright © Microsoft Corporation.
+
+extra:
+  generator: false
+
+# Configuration
+theme:
+  name: material
+  logo: images/favicon.png
+  favicon: images/favicon.ico
+  # custom_dir: overrides
+  font:
+    text: Inter
+    code: Fira Code
+  features:
+    - content.code.copy
+    - navigation.collapsible
+    - navigation.instant
+    - navigation.instant.preview
+    - navigation.tabs
+    - navigation.sections
+    - search.highlight
+    - search.share
+    - search.suggest
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode
+
+    # # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: custom
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      toggle:
+        icon: material/toggle-switch-off
+        name: Switch to system preference
 
 markdown_extensions:
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
   - admonition
   - def_list
-  - attr_list
 
+# Plugins
 plugins:
-  - search
-  - mermaid2
+  - search:
+      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - minify:
+      minify_html: true
+
+extra_javascript:
+  - https://unpkg.com/[email protected]/dist/tablesort.min.js
+  - javascripts/tablesort.js
+extra_css:
+  - stylesheets/extra.css
 
 nav:
-  - index.md
-  - before_you_start.md
-  - architecture.md
-  - software.md
-  - feature_flags.md
+  - Concepts:
+    - concepts_overview.md
+    - before_you_start.md
+    - feature_flags.md
+    - Architecture:
+      - architecture.md
+      - software.md
   - Tutorials:
-    - tutorial_cli.md
-    - tutorial_click.md
-    - tutorial_rest.md
-    - tutorial_vnet.md
-  - OSDU Services:
-    - osdu_source.md
-    - osdu_core.md
-    - osdu_reference.md
+    - tutorials_overview.md
+    - Deployment:
+      - tutorial_cli.md
+      - tutorial_click.md
+      - tutorial_rest.md
+    - Debugging:
+      - tutorial_logs.md
+      - tutorial_metrics.md
+    - Advanced Scenarios:
+      - tutorial_vnet.md
+  - Services:
+    - services_overview.md
+    - services_core.md
+    - services_reference.md

docs/src/index.md → docs/src/concepts_overview.md

@@ -1,6 +1,5 @@
-# OSDU Developer
+# Overview
 
-## Overview
 
 OSDU Developer is an open-source solution designed to enable the creation of lightweight, personal instances of [OSDU™](https://osduforum.org/osdu-data-platform-primer-1/) running on the Azure Public Cloud. These personal instances are tailored specifically for developers and work with the [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/overview). This allows engineers to explore and author applications or work directly on technology prior to the transition to a fully managed service offering. A simplified one-click deployment capability with less development features is also available.
 

docs/src/javascripts/tablesort.js

@@ -0,0 +1,6 @@
+document$.subscribe(function() {
+    var tables = document.querySelectorAll("article table:not([class])")
+    tables.forEach(function(table) {
+      new Tablesort(table)
+    })
+  })

docs/src/osdu_core.md → docs/src/services_core.md

@@ -1,4 +1,4 @@
-# Core Services
+# OSDU Core
 
 This repository can be used to hold the source code for the OSDU Core Services.
 

docs/src/osdu_source.md → docs/src/services_overview.md

@@ -1,4 +1,4 @@
-# Gitlab Source
+# Overview
 
 Welcome to the OSDU Source Code directory! This directory is structured to help you easily clone down the OSDU services and related repositories using the `gita` command.
 

docs/src/services_reference.md

@@ -0,0 +1 @@
+# OSDU Reference

docs/src/stylesheets/extra.css

@@ -0,0 +1,24 @@
+:root > * {
+    --md-typeset-a-color: #0199a1;
+    --md-footer-fg-color: hsla(0, 0%, 100%, 1);
+    --md-footer-fg-color--light: hsla(0, 0%, 100%, 0.7);
+    --md-footer-fg-color--lighter: hsla(0, 0%, 100%, 0.3);
+    --md-footer-bg-color: #01393b;;
+    --md-footer-bg-color--dark: #01393b;
+    --md-typeset-a-color: #0199a1;
+}
+
+[data-md-color-scheme="default"] {
+    --md-primary-fg-color: #01696e;
+    --md-accent-fg-color: #02c9d3;
+}
+
+[data-md-color-scheme="slate"] {
+    --md-primary-fg-color: #01393b;
+    --md-accent-fg-color: #02c9d3;
+}
+
+li.md-nav__item--section > label.md-nav__link > span.md-ellipsis {
+    color: #01696e;
+}
+

docs/src/tutorial._airflow.md

@@ -0,0 +1,3 @@
+# Working with Airflow
+
+Coming soon.