Revamp documentation structure and navigation

docconf/docconf/__init__.py

@@ -0,0 +1,2 @@
+# Expose config variables for Sphinx conf.py imports
+from .docconf import version, release, project, author, copyright, warning_is_error, extensions, templates_path, exclude_patterns, source_suffix, source_encoding, language, master_doc, rst_epilog, myst_substitutions, autosectionlabel_prefix_document, autosectionlabel_maxdepth, linkcheck_ignore, linkcheck_request_headers, linkcheck_timeout, linkcheck_retries, linkcheck_exclude_documents, spelling_word_list_filename, spelling_filters, spelling_exclude_patterns, html_theme, html_baseurl, html_favicon, html_static_path, html_show_sourcelink, html_show_sphinx, html_context, html_theme_options, myst_heading_anchors, suppress_warnings, myst_enable_extensions

docs/_static/custom_sitemap.css

@@ -0,0 +1,17 @@
+/* Custom styles for interactive sitemap */
+.sitemap-list {
+  list-style: none;
+  padding-left: 0;
+}
+.sitemap-list li {
+  margin: 0.2em 0;
+}
+.sitemap-toggle {
+  cursor: pointer;
+  font-weight: bold;
+  margin-right: 0.3em;
+}
+.sitemap-children {
+  margin-left: 1.5em;
+  display: none;
+}

docs/_static/custom_sitemap.js

@@ -0,0 +1,18 @@
+// Custom interactive sitemap JS for Sphinx
+// Simple collapsible tree for sitemap page
+
+document.addEventListener('DOMContentLoaded', function() {
+  var togglers = document.querySelectorAll('.sitemap-toggle');
+  togglers.forEach(function(toggler) {
+    toggler.addEventListener('click', function() {
+      var target = document.getElementById(this.dataset.target);
+      if (target.style.display === 'none') {
+        target.style.display = 'block';
+        this.textContent = '▼';
+      } else {
+        target.style.display = 'none';
+        this.textContent = '▶';
+      }
+    });
+  });
+});

docs/api/index.rst

@@ -1,9 +1,12 @@
+
 APIs
 ====
 
 The following APIs are available for the Edge Orchestrator:
 
 .. toctree::
+   :maxdepth: 2
+   :caption: API Reference
 
    alerting_monitor
    app_catalog

docs/conf.py

@@ -14,7 +14,7 @@
 if os.environ.get("SIMPLE_MODE") == "true":
     from docconf import docconf_simple as docconf
 else:
-    from docconf import docconf
+    from docconf.docconf import version, release, project, author, copyright, warning_is_error, extensions, templates_path, exclude_patterns, source_suffix, source_encoding, language, master_doc, rst_epilog, myst_substitutions, autosectionlabel_prefix_document, autosectionlabel_maxdepth, linkcheck_ignore, linkcheck_request_headers, linkcheck_timeout, linkcheck_retries, linkcheck_exclude_documents, spelling_word_list_filename, spelling_filters, spelling_exclude_patterns, html_theme, html_baseurl, html_favicon, html_static_path, html_show_sourcelink, html_show_sphinx, html_context, html_theme_options, myst_heading_anchors, suppress_warnings, myst_enable_extensions
 
 # sphinx doesn't use UPPER_CASE naming style for constants
 # pylint: disable=invalid-name
@@ -26,52 +26,34 @@
 # make changes to the docconf module - see the repo README for further
 # instructions.
 
-version = docconf.version
-release = docconf.release
-project = docconf.project
-author = docconf.author
-copyright = docconf.copyright  # pylint: disable=redefined-builtin
-
-warning_is_error = docconf.warning_is_error
-
-extensions = docconf.extensions
-
-templates_path = docconf.templates_path
-exclude_patterns = docconf.exclude_patterns
-
-source_suffix = docconf.source_suffix
-source_encoding = docconf.source_encoding
-
-language = docconf.language
-master_doc = docconf.master_doc
-rst_epilog = docconf.rst_epilog
-myst_substitutions = docconf.myst_substitutions
-
-autosectionlabel_prefix_document = docconf.autosectionlabel_prefix_document
-autosectionlabel_maxdepth = docconf.autosectionlabel_maxdepth
-
-linkcheck_ignore = docconf.linkcheck_ignore
-linkcheck_request_headers = docconf.linkcheck_request_headers
-linkcheck_timeout = docconf.linkcheck_timeout
-linkcheck_retries = docconf.linkcheck_retries
-linkcheck_exclude_documents = docconf.linkcheck_exclude_documents
-
-spelling_word_list_filename = docconf.spelling_word_list_filename
-spelling_filters = docconf.spelling_filters
-spelling_exclude_patterns = docconf.spelling_exclude_patterns
-
-html_theme = docconf.html_theme
-
-html_baseurl = docconf.html_baseurl
-html_favicon = docconf.html_favicon
-html_static_path = docconf.html_static_path
-html_show_sourcelink = docconf.html_show_sourcelink
-html_show_sphinx = docconf.html_show_sphinx
-
-html_context = docconf.html_context
-html_theme_options = docconf.html_theme_options
-
-# Configure myst_parser (only used by docconf_simple)
-myst_heading_anchors = docconf.myst_heading_anchors
-suppress_warnings = docconf.suppress_warnings
-myst_enable_extensions = docconf.myst_enable_extensions
+## Use direct imports for local builds
+## (see import above)
+
+## Remove all references to 'docconf.' prefix for local builds
+source_suffix = source_suffix
+source_encoding = source_encoding
+language = language
+master_doc = master_doc
+rst_epilog = rst_epilog
+myst_substitutions = myst_substitutions
+autosectionlabel_prefix_document = autosectionlabel_prefix_document
+autosectionlabel_maxdepth = autosectionlabel_maxdepth
+linkcheck_ignore = linkcheck_ignore
+linkcheck_request_headers = linkcheck_request_headers
+linkcheck_timeout = linkcheck_timeout
+linkcheck_retries = linkcheck_retries
+linkcheck_exclude_documents = linkcheck_exclude_documents
+spelling_word_list_filename = spelling_word_list_filename
+spelling_filters = spelling_filters
+spelling_exclude_patterns = spelling_exclude_patterns
+html_theme = html_theme
+html_baseurl = html_baseurl
+html_favicon = html_favicon
+html_static_path = html_static_path
+html_show_sourcelink = html_show_sourcelink
+html_show_sphinx = html_show_sphinx
+html_context = html_context
+html_theme_options = html_theme_options
+myst_heading_anchors = myst_heading_anchors
+suppress_warnings = suppress_warnings
+myst_enable_extensions = myst_enable_extensions

docs/deployment_guide/index.rst

@@ -1,18 +1,17 @@
+
 Deployment Guide
 ================
 
-You have the flexibility to deploy our |software_prod_name|\ using either
-Amazon Web Services\* (AWS\*) cloud or on-premises infrastructure, depending on
-your specific needs and preferences.
-
-To get started, refer to the following sections for detailed instructions and
-guidance tailored to each deployment option.
+You have the flexibility to deploy |software_prod_name| using either Amazon Web Services* (AWS*) cloud or on-premises infrastructure.
 
-* :doc:`cloud_deployment/index`
-* :doc:`on_prem_deployment/index`
+**Deployment Guide Navigation**
 
 .. toctree::
-   :hidden:
+   :maxdepth: 2
+   :caption: Deployment Guide Contents
 
    cloud_deployment/index
    on_prem_deployment/index
+
+**Section Overview**
+

docs/developer_guide/index.rst

@@ -1,67 +1,22 @@
 Developer Guide
 ===============
 
-|software_prod_name|, part of the Open Edge Platform, brings the ease
-of cloud-native deployment, orchestration, and management to edge environments,
-at scale.
+|software_prod_name|, part of the Open Edge Platform, brings the ease of cloud-native deployment, orchestration, and management to edge environments at scale.
 
-.. figure:: images/edge_platform_arch.png
-   :alt: High-Level Architecture of Open Edge Platform |software_prod_name|
+**Developer Guide Navigation**
+**Developer Guide Navigation**
+------------------------------
 
-Cloud computing abstracts away details of the underlying computing devices. In
-contrast, edge networks often require heterogeneous and specific hosts. You may
-need purpose-built equipment for networking, retail, or factory control in your
-edge. Alternatively, you may need to run AI models that have been optimized for
-performance on a specific class of devices.
-
-Additionally, hosts in an edge network may also have limited memory or compute
-power. They may be situated in remote environments that are hard to reach or in
-locations with physical security concerns. |software_prod_name| addresses
-the challenges of edge computing, streamlining the management of edge
-networks at scale.
-
-|software_prod_name| consists of seven main components, deployable on-premises
-or in the cloud:
-
-* **Edge Node Agents**: A set of agents that run on the edge nodes as OS-level agents.
-  They communicate with the services running in the |software_prod_name| and provide a
-  consistent interface for the edge node software. Read more about :doc:`agents/index`.
-
-* **Edge Infrastructure Manager**: Policy-based, secure lifecycle management
-  of a fleet of edge nodes/devices at scale, spread across distributed locations
-  allowing onboarding, provisioning, inventory management, upgrades and more.
-  Read more about :doc:`infra_manager/index`.
-
-* **Edge Cluster Orchestrator**: A lightweight multi-cluster orchestrator based
-  on the Cluster API (CAPI) standard, designed to automate the deployment and
-  lifecycle management of Kubernetes\* clusters at scale across distributed
-  edges, providing centralized monitoring and access control.
-  Read more about :doc:`cluster_orch/index`.
-
-* **Edge Application Orchestrator**: Offers customers the ability to easily
-  package, deploy and monitor cloud-native applications at scale across
-  distributed edges. Read more about :doc:`app_orch/index`.
-
-* **User Interface**: The web user interface for the Edge Orchestrator, allowing
-  the user to manage most of the features of the product in an intuitive,
-  visual, manner without having to trigger a series of APIs individually.
-
-* **Observability**: A modular observability stack that provides visibility into
-  the health and performance of the system, including logging, reporting,
-  alerts, and SRE data from Edge Orchestrator components and Edge Nodes.
-  Read more about :doc:`observability/index`.
-
-* **Platform Services**: A collection of services that support the deployment
-  and management of Edge Orchestrator, including Identity and Access
-  management, multitenancy management, ingress route configuration, secrets
-  and certificate management, cloud and on-prem infrastructure lifecycle
-  management and more. Read more about :doc:`platform/index`.
-
-All of the components are exposed via a seamless, consistent, intuitive, and
-delightful user experience.
-
-|software_prod_name| also includes software that gets installed into the Edge
-Node called **Edge Node Agents**.
+.. toctree::
+  :maxdepth: 2
+  :caption: Developer Guide Contents
+
+  platform/index
+  observability/index
+  virtual_edge_node/index
+  trusted_compute/index
+  contributor_guide/index
+  application_developer_workflow/index
 
 All of the artifacts needed to deploy |software_prod_name| and the Edge Nodes
 are published in the Release Service.