refactor: move to mkdocs-material

Signed-off-by: Mauro Sardara <[email protected]>

Author: msardara

.github/workflows/reusable-docs.yml

@@ -50,11 +50,6 @@ jobs:
         id: pages
         uses: actions/configure-pages@v5
 
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
       - name: Setup Golang
         uses: actions/setup-go@v5
         with:
@@ -65,6 +60,11 @@ jobs:
         run: |
           sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
 
+      - name: Setup UV
+        shell: bash
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+
       - name: Update GITHUB_PATH
         shell: bash
         run: echo "$HOME/.local/bin" >> $GITHUB_PATH
@@ -80,7 +80,7 @@ jobs:
         uses: actions/upload-pages-artifact@v3
         with:
           name: docs-website
-          path: ./.build/docs/html
+          path: ./.build/site
 
   deploy:
     name: Deploy artifacts

.gitignore

@@ -1,9 +1,14 @@
 # Build
 .build/
 venv/
+.venv
+site
 
 # Dependencies
 .dep/
 
 # Secrets
 .env
+
+# Generated files
+generated/

README.md

@@ -12,6 +12,7 @@ Markdown.
     - [macOS](#macos)
     - [Linux](#linux)
     - [Windows](#windows)
+  - [Running local live server](#running-local-live-server)
   - [Building the Documentation](#building-the-documentation)
   - [Contributing](#contributing)
 - [Copyright Notice](#copyright-notice)
@@ -23,36 +24,49 @@ To build the documentation locally, you need to install required dependencies.
 **Prerequisites**
 
 - [Taskfile](https://taskfile.dev/)
-- [Python](https://www.python.org/downloads/)
+- [Uv](https://docs.astral.sh/uv/getting-started/installation/)
 - [Golang](https://go.dev/doc/devel/release#go1.24.0)
 
 ### macOS
 
-- Install Taskfile using Homebrew:
+- Install Taskfile and uv using Homebrew:
 
    ```sh
    brew install go-task/tap/go-task
+   brew install uv
+   ```
 
 ### Linux
 
-- Install Taskfile using bash:
+- Install Taskfile and uv using bash:
 
    ```sh
    sh -c '$(curl -fsSL https://taskfile.dev/install.sh)'
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
 
 ### Windows
 
-- Install Taskfile using scoop:
+- Install Taskfile and uv using scoop:
 
    ```sh
    scoop install go-task
+   scoop install main/uv
+   ```
+
+## Running local live server
+
+   ```sh
+   task run
+   ```
 
 ## Building the Documentation
 
 - To build the documentation, run the following command:
 
    ```sh
    task build
+   ```
 
 - This will generate the HTML documentation in the .build/docs/html directory.
 
@@ -67,4 +81,4 @@ changes. Submit a pull request.
 
 [Copyright Notice and License](./LICENSE.md)
 
-Copyright AGNTCY Contributors (https://github.com/agentcy)
+Copyright AGNTCY Contributors (https://github.com/agentcy)

Taskfile.yml

@@ -26,49 +26,46 @@ tasks:
   build:
     desc: Build documentation website
     deps:
-      - deps/venv
+      - deps/patch
       - deps/proto-diagrams
     preconditions:
       - which go
-      - which python
     env:
-      SOURCE_DIR:     "{{.ROOT_DIR}}/docs"
       SCHEMA_DIR:     "{{.ROOT_DIR}}/schema"
       BUILD_DOCS_DIR: "{{.BUILD_DIR}}/docs"
     vars:
-      BUILD_SITE_DIR: "{{.BUILD_DIR}}/docs/html"
+      BUILD_SITE_DIR: "{{.BUILD_DIR}}/site"
     cmds:
-      - PATH={{.PATH}} ./docs/build-docs.sh
+      - mkdir -p docs/generated
+      - "{{.DEPS_DIR}}/proto-gen-md-diagrams -d ${SCHEMA_DIR} -o docs/generated"
+      - pushd mkdocs && uv run mkdocs build --site-dir {{.BUILD_SITE_DIR}} && popd
       - |
         echo "Docs available at: file://{{.BUILD_SITE_DIR}}/index.html"
 
-  # TODO(ramizpolic): This usually works well to regenerate context, but it's not a real hot-reload.
-  # Note that sometimes it crashes and goes into reload loop. Investigate or find alternative.
   run:
+    deps:
+      - deps/patch
+      - deps/proto-diagrams
     desc: Run documentation website in live editing mode
-    preconditions:
-      - which go
-      - which python
-    watch: true
-    sources:
-      - 'docs/**/*'
-      - 'schema/**/*'
     vars:
       BUILD_SITE_DIR: "{{.BUILD_DIR}}/docs/html"
     cmds:
-      - task: build
-      - |
-        echo "Docs available at: file://{{.BUILD_SITE_DIR}}/index.html"
+      - pushd mkdocs && uv run mkdocs serve
 
-  ##
-  ## Dependencies
-  ##
-  deps/venv:
+  # TODO(msardara): This is a workaround, the __init__.py files shohuld be in the acp-sdk repo
+  deps/patch:
     internal: true
+    dir: mkdocs
+    vars:
+      PYTHON_VERSION:
+        sh: echo "python$(cat .python-version)"
     cmds:
-      - python3 -m venv {{.VENV_DIR}}
-    status:
-      - test -f {{.VENV_DIR}}
+      - uv sync
+      - touch .venv/lib/{{.PYTHON_VERSION}}/site-packages/agntcy_acp/acp_v0/sync_client/__init__.py
+      - touch .venv/lib/{{.PYTHON_VERSION}}/site-packages/agntcy_acp/acp_v0/async_client/__init__.py
+    generates:
+      - .venv/lib/{{.PYTHON_VERSION}}/site-packages/agntcy_acp/acp_v0/sync_client
+      - .venv/lib/{{.PYTHON_VERSION}}/site-packages/agntcy_acp/acp_v0/async_client
 
   deps/proto-diagrams:
     internal: true

docs/.index

@@ -0,0 +1,11 @@
+nav:
+  - INTRODUCTION: index.md
+  - OASF: oasf
+  - AGENT DIRECTORY SERVICE: dir
+  - AGENT MANIFEST: manifest
+  - SEMANTIC SDK: semantic-sdk
+  - SYNTACTIC SDK: syntactic-sdk
+  - MESSAGING SDK: messaging-sdk
+  - AGENT WORKFLOW SERVER: agws
+  - CSIT: csit
+  - HOW-TOs: how-to-guides

docs/_static/css/theme.custom.css

@@ -0,0 +1,3 @@
+nav:
+  - Agent Workflow Server: workflow_server.md
+  - Workflow Server Manager: workflow_server_manager.md