[skip ci] 📝 Add API docs & workflow to async_context

.github/workflows/api.yml

@@ -0,0 +1,32 @@
+# Copyright 2024 - 2025 Khalil Estell and the libhal contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: 📚 Deploy APIs
+
+on:
+  release:
+    types:
+      - published
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  api:
+    uses: libhal/ci/.github/workflows/api_docs_gen.yml@5.x.y
+    secrets: inherit

docs/_static/extra.css

@@ -0,0 +1,62 @@
+h1 {
+    color: orange;
+    font-size: 2em;
+}
+
+
+/* anything related to the dark theme */
+html[data-theme="dark"] {
+
+    /* whatever you want to change */
+    img {
+        background: transparent !important;
+    }
+}
+
+html[data-theme="light"] {
+
+    /* whatever you want to change */
+    img {
+        background: transparent !important;
+    }
+
+
+}
+
+.md-typeset h2 {
+    font-size: 1.5em;
+}
+
+a code {
+    color: #2980B9;
+}
+
+a:hover code {
+    color: #3091d1;
+}
+
+a:visited code {
+    color: #9B59B6;
+}
+
+.md-header__topic {
+    font-size: 1.6em;
+    font-weight: 100 !important;
+}
+
+.md-logo {
+    margin: 0px !important;
+    padding: 0px !important;
+}
+
+.md-logo img {
+    height: 2.2rem !important;
+}
+
+.md-tabs__link {
+    font-size: .8rem !important;
+}
+
+.wy-nav-content {
+    max-width: none;
+}

docs/_templates/guide_links.html

@@ -0,0 +1,68 @@
+{# Displays links to the top-level TOCtree elements, in the header navbar. #}
+<nav class="navbar-nav">
+  <p
+    class="sidebar-header-items__title"
+    role="heading"
+    aria-level="2"
+    aria-label="{{ _('Site Navigation') }}"
+  ></p>
+  <ul class="bd-navbar-elements navbar-nav">
+    <li class="nav-item dropdown">
+      <button
+        class="btn dropdown-toggle nav-item"
+        type="button"
+        data-bs-toggle="dropdown"
+        aria-expanded="false"
+        aria-controls="pst-nav-more-links"
+      >
+        Guides
+      </button>
+      <ul id="pst-nav-more-links" class="dropdown-menu">
+        <li class="nav-item">
+          <a
+            class="nav-link dropdown-item nav-external"
+            href="https://libhal.github.io/"
+          >
+            🏡 Introduction
+          </a>
+        </li>
+
+        <li class="nav-item">
+          <a
+            class="nav-link dropdown-item nav-external"
+            href="https://libhal.github.io/getting_started/"
+          >
+            🚀 Getting Started
+          </a>
+        </li>
+
+        <li class="nav-item">
+          <a
+            class="nav-link dropdown-item nav-external"
+            href="https://libhal.github.io/user_guide/fundamentals/"
+          >
+            📖 User Guide
+          </a>
+        </li>
+
+        <li class="nav-item">
+          <a
+            class="nav-link dropdown-item nav-external"
+            href="https://libhal.github.io/contributor_guide/philosophy/"
+          >
+            📚 Contributor Guides
+          </a>
+        </li>
+
+        <li class="nav-item">
+          <a
+            class="nav-link dropdown-item nav-external"
+            href="https://libhal.github.io/project_information/status/"
+          >
+            📊 Project Information
+          </a>
+        </li>
+      </ul>
+    </li>
+  </ul>
+</nav>

docs/_templates/layout.html

@@ -0,0 +1 @@
+{% extends "!layout.html" %}

docs/api/async_context.md

@@ -0,0 +1,55 @@
+# async_context
+
+## async::context
+
+Defined in namespace `async::v0`
+
+*import async_context;*
+
+```{doxygenclass} v0::context
+```
+
+## async::basic_context
+
+Defined in namespace `async::v0`
+
+*import async_context;*
+
+```{doxygenclass} v0::basic_context
+```
+
+## async::proxy_context
+
+Defined in namespace `async::v0`
+
+*import async_context;*
+
+```{doxygenclass} v0::proxy_context
+```
+
+## async::exclusive_access
+
+Defined in namespace `async::v0`
+
+*import async_context;*
+
+```{doxygenclass} v0::exclusive_access
+```
+
+## async::blocked_by
+
+Defined in namespace `async::v0`
+
+*import async_context;*
+
+```{doxygenenum} v0::blocked_by
+```
+
+## async::future\<T\>
+
+Defined in namespace `async::v0`
+
+*import async_context;*
+
+```{doxygenclass} v0::future
+```

docs/api/index.rst

@@ -0,0 +1,12 @@
+async_context API
+===============
+
+Defined in namespace ``async::v0``
+
+*import async_context;*
+
+.. toctree::
+    :caption: Types
+    :maxdepth: 2
+
+    async_context

docs/conf.py

@@ -0,0 +1,76 @@
+from sphinx.application import Sphinx
+from pathlib import Path
+import json
+import os
+import re
+
+if not os.environ.get('LIBHAL_API_VERSION'):
+    print("\nEnvironment variable 'LIBHAL_API_VERSION' must be set!")
+    exit(1)
+
+API_VERSION = os.environ.get('LIBHAL_API_VERSION')
+
+doxygen_conf = Path('doxygen.conf').read_text()
+match = re.search(r'PROJECT_NAME\s*=\s*"([^"]+)"', doxygen_conf)
+if not match:
+    print("\nCould not find PROJECT_NAME in doxygen.conf!")
+    exit(1)
+LIBRARY_NAME = match.group(1)
+
+DEFAULT_SWITCHER_URL = f"https://libhal.github.io/api/{LIBRARY_NAME}/switcher.json"
+
+LOCAL_BUILD = os.environ.get('LIBHAL_LOCAL_BUILD')
+
+if LOCAL_BUILD:
+    switcher_url = "switcher.json"
+else:
+    switcher_url = DEFAULT_SWITCHER_URL
+
+html_theme = 'pydata_sphinx_theme'
+html_theme_options = {
+    "navbar_start": ["navbar-logo", "guide_links", "version-switcher"],
+    "navbar_center": ["navbar-nav"],
+    "navbar_end": ["navbar-icon-links"],
+    "navbar_persistent": ["search-button-field", "theme-switcher"],
+    "header_links_before_dropdown": 3,
+    "switcher": {
+        "json_url": switcher_url,
+        "version_match": API_VERSION,
+    },
+    "check_switcher": False,
+}
+
+extensions = ["breathe", "myst_parser"]
+
+
+def write_local_switcher(app, exception):
+    if LOCAL_BUILD and exception is None:
+        outdir = Path(app.outdir)
+        (outdir / 'switcher.json').write_text(
+            json.dumps([{"version": API_VERSION, "url": "."}]))
+
+
+def setup(app: Sphinx):
+    app.add_css_file("extra.css")
+    app.connect("build-finished", write_local_switcher)
+
+
+html_css_files = [
+    'extra.css',
+]
+breathe_projects = {LIBRARY_NAME: "build/xml"}
+breathe_default_project = LIBRARY_NAME
+breathe_default_members = ('members',)
+project = LIBRARY_NAME
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown'
+}
+master_doc = 'index'
+exclude_patterns = ['.venv', 'build']
+highlight_language = 'c++'
+html_static_path = ['_static']
+templates_path = ['_templates']
+todo_include_todos = False
+html_favicon = "_static/favicon.ico"
+html_logo = "_static/logo.png"

docs/index.rst

@@ -0,0 +1,15 @@
+async_context API documentation
+=======================================
+
+**Welcome to async_context API documentation**
+
+`async_context` is a lightweight, C++23 coroutine library for embedded systems
+and resource-constrained environments. Built with stack-based allocation to
+avoid heap usage and designed to fit within a single cache line for optimal
+performance.
+
+.. toctree::
+  :caption: async_context Docs
+  :maxdepth: 5
+
+  async_context API <api/index>

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx>=8.1.3
+pydata-sphinx-theme>=0.16.1
+myst_parser>=4.0.1
+breathe>=4.36.0