Restructured the toc. (#217)

Azure · Oct 7, 2024 · 2db213a · 2db213a
1 parent 22536db
commit 2db213a
Show file tree

Hide file tree

Showing 19 changed files with 181 additions and 92 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -54,7 +54,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: pip install mkdocs mkdocs-material mkdocs-minify-plugin
+      - run: pip install mkdocs mkdocs-material mkdocs-minify-plugin mkdocs-git-committers-plugin-2 mkdocs-git-revision-date-localized-plugin
       - run: |
           cd docs
           mkdocs gh-deploy --force --clean --verbose

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -34,7 +34,9 @@ theme:
     - navigation.instant
     - navigation.instant.preview
     - navigation.tabs
-    - navigation.sections
+    # - navigation.tabs.sticky
+    # - navigation.sections
+    - navigation.expand
     - search.highlight
     - search.share
     - search.suggest
@@ -63,15 +65,19 @@ theme:
 
 markdown_extensions:
   - attr_list
+  - md_in_html
   - 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.details
   - pymdownx.inlinehilite
   - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
@@ -88,6 +94,13 @@ plugins:
       separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
   - minify:
       minify_html: true
+  - git-revision-date-localized:
+      enable_creation_date: true
+      enabled: !ENV [CI, false]
+  - git-committers:
+      repository: azure/osdu-developer
+      branch: main
+      enabled: !ENV [CI, false]
 
 extra_javascript:
   - https://unpkg.com/[email protected]/dist/tablesort.min.js
@@ -97,24 +110,28 @@ extra_css:
 
 nav:
   - Concepts:
-    - concepts_overview.md
-    - before_you_start.md
+    - overview.md
+    - getting_started.md
     - feature_flags.md
-    - Architecture:
-      - architecture.md
-      - software.md
+    - Design:
+      - design_architecture.md
+      - design_infrastructure.md
+      - design_software.md
   - Tutorials:
-    - tutorials_overview.md
     - Deployment:
       - tutorial_cli.md
-      - tutorial_click.md
-      - tutorial_rest.md
+      - tutorial_arm.md
     - Debugging:
-      - tutorial_logs.md
-      - tutorial_metrics.md
+      - debugging_rest.md
+      - debugging_istio.md
+      - debugging_airflow.md
+      - debugging_kibana.md
     - Advanced Scenarios:
-      - tutorial_vnet.md
+      - advanced_vnet.md
   - Services:
     - services_overview.md
-    - services_core.md
-    - services_reference.md
+    - OSDU:
+      - services_core.md
+      - services_reference.md
+    - Experimental:
+      - experimental_adminui.md
diff --git a/docs/src/tutorial_vnet.md → docs/src/advanced_vnet.md b/docs/src/tutorial_vnet.md → docs/src/advanced_vnet.md
@@ -1,4 +1,4 @@
-# Using a Custom Network
+# Custom Networks
 
 The provided custom deployment solution is a sample of how to leverage the virtual network (VNet) injection feature. This allows for the integration of the solution into a preexisting network design and ensuring the solution is on an internal network.
 

diff --git a/docs/src/concepts_overview.md b/docs/src/concepts_overview.md
diff --git a/docs/src/debugging_airflow.md b/docs/src/debugging_airflow.md
@@ -0,0 +1,3 @@
+# Airflow
+
+Coming Soon
diff --git a/docs/src/debugging_istio.md b/docs/src/debugging_istio.md
@@ -0,0 +1,3 @@
+# Istio
+
+Coming Soon
diff --git a/docs/src/debugging_kibana.md b/docs/src/debugging_kibana.md
@@ -0,0 +1,3 @@
+# Kibana
+
+Coming Soon
diff --git a/docs/src/tutorial_rest.md → docs/src/debugging_rest.md b/docs/src/tutorial_rest.md → docs/src/debugging_rest.md
@@ -1,4 +1,4 @@
-# Test using REST scripts
+# REST Samples
 
 The solution has an integrated capability for the immediate execution of Rest API's using visual studio code. This integration only occurs if the Azure Developer CLI installation process has been performed.
 

diff --git a/docs/src/architecture.md → docs/src/design_architecture.md b/docs/src/architecture.md → docs/src/design_architecture.md
diff --git a/docs/src/design_infrastructure.md b/docs/src/design_infrastructure.md
@@ -0,0 +1 @@
+# Infrastructure
diff --git a/docs/src/software.md → docs/src/design_software.md b/docs/src/software.md → docs/src/design_software.md
@@ -1,4 +1,4 @@
-# Software Management
+# Software
 
 ### Stamp Layout
 

diff --git a/docs/src/experimental_adminui.md b/docs/src/experimental_adminui.md
@@ -0,0 +1,3 @@
+# Admin UI
+
+Coming Soon
diff --git a/docs/src/before_you_start.md → docs/src/getting_started.md b/docs/src/before_you_start.md → docs/src/getting_started.md
@@ -1,4 +1,4 @@
-# Before you start
+# Getting Started
 
 Before starting it is important to ensure the Azure Subscription is properly configured for a personal instance.
 

diff --git a/docs/src/overview.md b/docs/src/overview.md
@@ -0,0 +1,125 @@
+# 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 transitioning to a fully managed service offering. A simplified one-click deployment capability, with fewer development features, is also available.
+
+!!! Note
+    Microsoft recommends using [Azure Data Manager for Energy (ADME)](https://azure.microsoft.com/en-us/products/data-manager-for-energy) for production workloads and integration testing.
+
+The primary goal of this solution is to provide an environment that functions within an inner loop process, delivering faster feedback for developers. This personal environment is user-friendly while maintaining compliance with varying organizational standards. It offers a flexible framework to facilitate deeper exploration of OSDU™ capabilities.
+
+![[0]][0]
+
+Deploying personal instances provides valuable insights into early-stage development and integration processes. This approach emphasizes transparency, cost-efficiency, and flexibility, empowering developers to engage in essential application and cloud development scenarios.
+
+??? Tip "Learning Opportunities"
+    Learn more about how inner and outer loop concepts can enhance developer productivity by viewing a discussion with Scott Hanselman, VP of Developer Community at Microsoft, on the Planet Argon Podcast: [The Fear Factor in Maintainable Software](https://www.youtube.com/watch?v=V5OhIjn7pJo).
+
+## Personas
+
+The Open Subsurface Data Universe (OSDU) platform is utilized by a variety of personas within the energy industry.
+
+<div class="grid cards" markdown>
+
+-   :fontawesome-solid-code:{ .lg .middle } __Application Developers__
+
+    ---
+
+    Build applications leveraging OSDU APIs to manage subsurface data efficiently.
+
+
+-   :fontawesome-solid-database:{ .lg .middle } __Data Engineers__
+
+    ---
+
+    Ensure proper data ingestion, transformation, and accessibility within the OSDU ecosystem.
+
+
+-   :fontawesome-solid-chart-line:{ .lg .middle } __Data Scientists__
+
+    ---
+
+    Analyze large volumes of subsurface data to derive insights using machine learning and statistical methods.
+
+
+-   :fontawesome-solid-cloud:{ .lg .middle } __IT and Cloud Architects__
+
+    ---
+
+    Design scalable, secure infrastructure to support the OSDU platform and integrate it with cloud services.
+
+
+-   :fontawesome-solid-user-tie:{ .lg .middle } __Domain Experts__
+
+    ---
+
+    Utilize their specialized knowledge to develop domain-specific applications and services on the OSDU platform.
+
+
+</div>
+
+## Benefits
+
+:material-eye-outline: **Observability:** Interact directly with resources and software components within the solution to enhance observability through logs, dashboards, and source code debugging.
+
+:material-cash: **Affordability:** Deploy with minimal resource consumption by omitting costly features like disaster recovery and backups, minimizing operational costs.
+
+:material-swap-horizontal-bold: **Flexibility:** The solution provides adaptable infrastructure to meet various organizational needs, including:
+
+=== "Virtual Network Injection"
+
+    Flexible network designs, including site-to-site VPN connections and integration with preexisting networks.
+
+=== "Controlled Access"
+
+    Public or private ingress, with the option to layer custom routing solutions for ingress, such as Azure Firewall or Azure Front Door.
+
+=== "Software Isolation"
+
+    Override and isolate software configurations as well as extend with custom configurations.
+
+
+## Scenarios
+
+Several different scenarios illustrate the practical applications of this approach:
+
+:material-cog: __Service Development__
+
+Create, update, debug, and work directly with OSDU services.
+
+
+:fontawesome-solid-laptop-code: __Application Development__
+
+Streamlined development for applications before integration with a managed service offering.
+
+
+:fontawesome-solid-lightbulb: __Technology Innovation__
+
+Fork and extend projects to explore deeper integration with various technologies such as Azure Fabric, Co-Pilot, and Power Platform.
+
+
+:material-school: __Training and Onboarding__
+
+Train new employees on the OSDU™ platform, offering hands-on experience in a controlled environment.
+
+
+
+## Features
+
+| **Feature**            | **Description**                                                                                                    |
+|------------------------|--------------------------------------------------------------------------------------------------------------------|
+| **Data Partitions**     | Supports a single data partition, named "opendes," for managing and organizing data within the platform.           |
+| **Schema Loading**      | Automatically loads Well-Known Schemas for efficient data management and validation.                               |
+| **Software Locations**  | Utilizes Flux to direct software loading processes to private GitHub repositories and branches.                    |
+| **Ingress**             | Supports both public-facing and private network access points.                                                     |
+| **Network Flexibility** | Enables VNet injection and integration with existing networks, allowing for S2S VPN access.                        |
+| **Mesh Observability**  | Provides Istio observability through Kiali dashboards to investigate latency, traffic, errors, and saturation.     |
+| **Elastic Tools**       | Integrates with Elastic Kibana for advanced dev tools, search capabilities, and user management.                  |
+| **Application Logging** | Integrated with Application Insights for detailed service-level logging and metrics monitoring.                    |
+| **Initial User**        | Includes initial user setup and configuration for OpenID Connect access.                                           |
+| **REST Scripts**        | Includes integrated sample REST scripts for easily executing API calls to test and explore functionality.          |
+| **Token Tools**         | Integrates access token tools for easy retrieval of Bearer Access Tokens via Swagger pages and docs.               |
+
+
+
+[0]: images/overview_1.png "Overview Diagram"
+[1]: images/overview_2.png "Use Cases Diagram"
diff --git a/docs/src/services_core.md b/docs/src/services_core.md
@@ -1,4 +1,4 @@
-# OSDU Core
+# Core Services
 
 This repository can be used to hold the source code for the OSDU Core Services.
 

diff --git a/docs/src/services_overview.md b/docs/src/services_overview.md
@@ -1,4 +1,4 @@
-# Overview
+# Source Code
 
 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.
 

diff --git a/docs/src/services_reference.md b/docs/src/services_reference.md
@@ -1 +1,3 @@
-# OSDU Reference
+# Reference Services
+
+Coming Soon
diff --git a/docs/src/tutorial_click.md → docs/src/tutorial_arm.md b/docs/src/tutorial_click.md → docs/src/tutorial_arm.md
@@ -1,4 +1,4 @@
-# Deploy using One Click
+# Portal Template (ARM)
 
 The solution is a native bicep solution and includes a transpiled ARM template from the latest release.  This ARM template can then be easily used as a custom template deployment.
 

diff --git a/docs/src/tutorial_cli.md b/docs/src/tutorial_cli.md
@@ -1,4 +1,4 @@
-# Deploy using AZD
+# Command Line (AZD)
 
 The process for working with the solution using the Azure Developer CLI is the recommended way for deployent offering the most flexibility.  This process can be used if working directly with the solution on a computer, working in a Visual Studio Code remote container, or using a cloud environment like Github Codespaces.