From 2db213ae115cfdfb9e4f98464ccf15610ebe8dd2 Mon Sep 17 00:00:00 2001 From: danielscholl Date: Mon, 7 Oct 2024 10:45:13 -0500 Subject: [PATCH] Restructured the toc. (#217) --- .github/workflows/documentation.yml | 2 +- docs/mkdocs.yml | 45 +++++-- .../{tutorial_vnet.md => advanced_vnet.md} | 2 +- docs/src/concepts_overview.md | 68 ---------- docs/src/debugging_airflow.md | 3 + docs/src/debugging_istio.md | 3 + docs/src/debugging_kibana.md | 3 + .../{tutorial_rest.md => debugging_rest.md} | 2 +- ...architecture.md => design_architecture.md} | 0 docs/src/design_infrastructure.md | 1 + docs/src/{software.md => design_software.md} | 2 +- docs/src/experimental_adminui.md | 3 + ...before_you_start.md => getting_started.md} | 2 +- docs/src/overview.md | 125 ++++++++++++++++++ docs/src/services_core.md | 2 +- docs/src/services_overview.md | 2 +- docs/src/services_reference.md | 4 +- .../{tutorial_click.md => tutorial_arm.md} | 2 +- docs/src/tutorial_cli.md | 2 +- 19 files changed, 181 insertions(+), 92 deletions(-) rename docs/src/{tutorial_vnet.md => advanced_vnet.md} (99%) delete mode 100644 docs/src/concepts_overview.md create mode 100644 docs/src/debugging_airflow.md create mode 100644 docs/src/debugging_istio.md create mode 100644 docs/src/debugging_kibana.md rename docs/src/{tutorial_rest.md => debugging_rest.md} (97%) rename docs/src/{architecture.md => design_architecture.md} (100%) create mode 100644 docs/src/design_infrastructure.md rename docs/src/{software.md => design_software.md} (99%) create mode 100644 docs/src/experimental_adminui.md rename docs/src/{before_you_start.md => getting_started.md} (99%) create mode 100644 docs/src/overview.md rename docs/src/{tutorial_click.md => tutorial_arm.md} (99%) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index a4fa9fea..9c0352ed 100644 --- 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 index 22cdab32..4fc0700e 100644 --- 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,6 +65,7 @@ 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 @@ -70,8 +73,11 @@ markdown_extensions: 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/tablesort@5.3.0/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 \ No newline at end of file + - OSDU: + - services_core.md + - services_reference.md + - Experimental: + - experimental_adminui.md \ No newline at end of file diff --git a/docs/src/tutorial_vnet.md b/docs/src/advanced_vnet.md similarity index 99% rename from docs/src/tutorial_vnet.md rename to docs/src/advanced_vnet.md index c2868fec..e32fea29 100644 --- a/docs/src/tutorial_vnet.md +++ b/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 deleted file mode 100644 index f23f681e..00000000 --- a/docs/src/concepts_overview.md +++ /dev/null @@ -1,68 +0,0 @@ -# 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. - -!!! Note - Microsoft recommends using [Azure Data Manager for Energy (ADME)](https://azure.microsoft.com/en-us/products/data-manager-for-energy) on production workloads and integration testing. - -The primary goal for this solution is to provide an environment that can help function within an inner loop process providing faster feedback for developers. This personal environment strives to be user-friendly yet maintain compliance with varying organizational standards. It offers a flexible framework to facilitate deeper exploration of OSDU™ capabilities. - -![[0]][0] - -Deploying personal instances provide valuable insights into early-stage development and integration processes. It emphasizes transparency, cost-efficiency, and flexibility, empowering developers to engage in essential application and cloud development scenarios. - -!!! Note - Learn more about how inner and outer loop concepts can enhance developer productivity by viewing a discusion 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) - -### Key Benefits - -**Observability and Transparency:** Interact directly with resource and software components within the solution to facilitate enhanced observability through logs, dashboards, and source code debugging. - -**Cost Efficiency:** Deploy with minimal resource consumption omitting costly features like disaster recovery and backup to minimize consumption costs. - -**Flexibility:** Provide adaptable infrastructure to meet various organizational needs. - -- 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 your own routing solutions for ingress, such as Azure Firewall or Azure Front Door. - -- Software Isolation - Override and isolate defined software configurations as well as extend with custom configurations. - -### Use Cases - -Several use cases illustrate the practical applications for this approach. - -**Service Development:** Create, update, debug, and work directly with OSDU services. - -**Application Development:** Easy development for applications prior to integration with a managed service offering. - -**Technology Innovation:** Fork and extend exploring deeper integration with various technologies such as Azure Fabric, Co-Pilot, and Power Platform. - -**Training and Onboarding:** Train new employees on the OSDU™ platform, offering hands-on experience in a controlled environment. - -![[1]][1] - - -## Features - - | **Feature** | **Description** | -|------------------------|--------------------------------------------------------------------------------------------------------------------| -| Data Partitions | Supports a single data partition for managing and organizing data within the platform, named "opendes." | -| Schema Loading | Automatically loads Well Known Schemas for efficient data management and validation. | -| Software Locations | Utilizes Flux to direct the software loading process to private GitHub repositories and branches. | -| Ingress | Supports both public-facing and private network access points. | -| Network flexibility | Supports VNet injection and integration with existing networks, to easily allow for S2S Vpn access. | -| Mesh Observability | Provides observability for istio using Kiali dashboards to investigate latency, traffic, errors, and saturation. | -| Elastic Tools | Supports connectivity to Elastic Kibana for advanced devtools, 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 | Integrated Sample Rest Scripts for easily executing API calls to test and explore functionality. | -| Token Tools | Integrated Access Token Tools for easy retrieval of Bearer Access Tokens for with Swagger Pages and docs. | - -## About this guide - -Follow the instructions in the "Tutorials" to quickly bring online a personal instance. - -[0]: images/overview_1.png "Overview Diagram" -[1]: images/overview_2.png "Use Cases Diagram" \ No newline at end of file diff --git a/docs/src/debugging_airflow.md b/docs/src/debugging_airflow.md new file mode 100644 index 00000000..d6a64eb5 --- /dev/null +++ b/docs/src/debugging_airflow.md @@ -0,0 +1,3 @@ +# Airflow + +Coming Soon \ No newline at end of file diff --git a/docs/src/debugging_istio.md b/docs/src/debugging_istio.md new file mode 100644 index 00000000..fee508d9 --- /dev/null +++ b/docs/src/debugging_istio.md @@ -0,0 +1,3 @@ +# Istio + +Coming Soon \ No newline at end of file diff --git a/docs/src/debugging_kibana.md b/docs/src/debugging_kibana.md new file mode 100644 index 00000000..3f7cc772 --- /dev/null +++ b/docs/src/debugging_kibana.md @@ -0,0 +1,3 @@ +# Kibana + +Coming Soon \ No newline at end of file diff --git a/docs/src/tutorial_rest.md b/docs/src/debugging_rest.md similarity index 97% rename from docs/src/tutorial_rest.md rename to docs/src/debugging_rest.md index 9c33a7f9..8ddbb21e 100644 --- a/docs/src/tutorial_rest.md +++ b/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 b/docs/src/design_architecture.md similarity index 100% rename from docs/src/architecture.md rename to docs/src/design_architecture.md diff --git a/docs/src/design_infrastructure.md b/docs/src/design_infrastructure.md new file mode 100644 index 00000000..62fce505 --- /dev/null +++ b/docs/src/design_infrastructure.md @@ -0,0 +1 @@ +# Infrastructure \ No newline at end of file diff --git a/docs/src/software.md b/docs/src/design_software.md similarity index 99% rename from docs/src/software.md rename to docs/src/design_software.md index 410e6b5b..2e67e51d 100644 --- a/docs/src/software.md +++ b/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 new file mode 100644 index 00000000..e7585039 --- /dev/null +++ b/docs/src/experimental_adminui.md @@ -0,0 +1,3 @@ +# Admin UI + +Coming Soon \ No newline at end of file diff --git a/docs/src/before_you_start.md b/docs/src/getting_started.md similarity index 99% rename from docs/src/before_you_start.md rename to docs/src/getting_started.md index e6323830..bf20d66c 100644 --- a/docs/src/before_you_start.md +++ b/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 new file mode 100644 index 00000000..c0eae0c5 --- /dev/null +++ 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. + +
+ +- :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. + + +
+ +## 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" \ No newline at end of file diff --git a/docs/src/services_core.md b/docs/src/services_core.md index 11d0ab47..7d336657 100644 --- 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 index 933c9993..5072047d 100644 --- 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 index aec3b1bb..d40b288b 100644 --- a/docs/src/services_reference.md +++ b/docs/src/services_reference.md @@ -1 +1,3 @@ -# OSDU Reference \ No newline at end of file +# Reference Services + +Coming Soon \ No newline at end of file diff --git a/docs/src/tutorial_click.md b/docs/src/tutorial_arm.md similarity index 99% rename from docs/src/tutorial_click.md rename to docs/src/tutorial_arm.md index c059df5b..12bb4351 100644 --- a/docs/src/tutorial_click.md +++ b/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 index 06bc2177..a56b04b3 100644 --- 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.