From 9c958127461bb5e657f94f8d01fcdf82b37685c6 Mon Sep 17 00:00:00 2001 From: shivashanmugam Date: Sat, 25 Apr 2026 13:54:28 +0530 Subject: [PATCH 1/3] adding api reference section Co-authored-by: Copilot --- .github/workflows/pages.yml | 29 +- docs/api-reference-guide.md | 599 ++++++++++++++++++ docs/api-reference/microbots/MicroBot.md | 5 + docs/api-reference/microbots/bot/AgentBoss.md | 1 + .../microbots/bot/BrowsingBot.md | 1 + .../api-reference/microbots/bot/CopilotBot.md | 1 + .../microbots/bot/LogAnalysisBot.md | 1 + .../api-reference/microbots/bot/ReadingBot.md | 1 + .../api-reference/microbots/bot/WritingBot.md | 1 + docs/api-reference/microbots/constants.md | 1 + .../microbots/environment/Environment.md | 1 + .../local_docker/LocalDockerEnvironment.md | 1 + .../image_builder/ShellCommunicator.md | 1 + .../local_docker/image_builder/dockerShell.md | 1 + docs/api-reference/microbots/extras/mount.md | 1 + docs/api-reference/microbots/index.md | 1 + .../microbots/llm/anthropic_api.md | 1 + docs/api-reference/microbots/llm/llm.md | 1 + .../microbots/llm/ollama_local.md | 1 + .../api-reference/microbots/llm/openai_api.md | 1 + .../microbots/tools/external_tool.md | 1 + .../microbots/tools/internal_tool.md | 1 + docs/api-reference/microbots/tools/tool.md | 1 + .../tools/tool_definitions/memory_tool.md | 1 + .../tool_definitions/microbot_sub_agent.md | 1 + .../microbots/tools/tool_yaml_parser.md | 1 + .../microbots/utils/copilot_auth.md | 1 + docs/api-reference/microbots/utils/logger.md | 1 + .../microbots/utils/multi_agent_log_parser.md | 1 + docs/api-reference/microbots/utils/network.md | 1 + docs/api-reference/microbots/utils/path.md | 1 + docs/javascripts/doc-anchors.js | 15 + docs/stylesheets/extra.css | 32 + mkdocs.yml | 64 +- src/microbots/environment/__init__.py | 0 .../local_docker/image_builder/__init__.py | 0 src/microbots/tools/__init__.py | 0 src/microbots/utils/__init__.py | 0 38 files changed, 768 insertions(+), 4 deletions(-) create mode 100644 docs/api-reference-guide.md create mode 100644 docs/api-reference/microbots/MicroBot.md create mode 100644 docs/api-reference/microbots/bot/AgentBoss.md create mode 100644 docs/api-reference/microbots/bot/BrowsingBot.md create mode 100644 docs/api-reference/microbots/bot/CopilotBot.md create mode 100644 docs/api-reference/microbots/bot/LogAnalysisBot.md create mode 100644 docs/api-reference/microbots/bot/ReadingBot.md create mode 100644 docs/api-reference/microbots/bot/WritingBot.md create mode 100644 docs/api-reference/microbots/constants.md create mode 100644 docs/api-reference/microbots/environment/Environment.md create mode 100644 docs/api-reference/microbots/environment/local_docker/LocalDockerEnvironment.md create mode 100644 docs/api-reference/microbots/environment/local_docker/image_builder/ShellCommunicator.md create mode 100644 docs/api-reference/microbots/environment/local_docker/image_builder/dockerShell.md create mode 100644 docs/api-reference/microbots/extras/mount.md create mode 100644 docs/api-reference/microbots/index.md create mode 100644 docs/api-reference/microbots/llm/anthropic_api.md create mode 100644 docs/api-reference/microbots/llm/llm.md create mode 100644 docs/api-reference/microbots/llm/ollama_local.md create mode 100644 docs/api-reference/microbots/llm/openai_api.md create mode 100644 docs/api-reference/microbots/tools/external_tool.md create mode 100644 docs/api-reference/microbots/tools/internal_tool.md create mode 100644 docs/api-reference/microbots/tools/tool.md create mode 100644 docs/api-reference/microbots/tools/tool_definitions/memory_tool.md create mode 100644 docs/api-reference/microbots/tools/tool_definitions/microbot_sub_agent.md create mode 100644 docs/api-reference/microbots/tools/tool_yaml_parser.md create mode 100644 docs/api-reference/microbots/utils/copilot_auth.md create mode 100644 docs/api-reference/microbots/utils/logger.md create mode 100644 docs/api-reference/microbots/utils/multi_agent_log_parser.md create mode 100644 docs/api-reference/microbots/utils/network.md create mode 100644 docs/api-reference/microbots/utils/path.md create mode 100644 docs/javascripts/doc-anchors.js create mode 100644 src/microbots/environment/__init__.py create mode 100644 src/microbots/environment/local_docker/image_builder/__init__.py create mode 100644 src/microbots/tools/__init__.py create mode 100644 src/microbots/utils/__init__.py diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 44fe9c7f..5e201fe4 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -26,8 +26,33 @@ jobs: with: python-version: "3.x" - - name: Install Zensical - run: pip install zensical + - name: Install Zensical and plugins + run: pip install zensical mkdocstrings[python] + + - name: Generate API reference stubs + run: | + python -c " + import os, re + from pathlib import Path + + src = Path('src') + docs_ref = Path('docs/api-reference') + + # Walk source tree and create stub md files with mkdocstrings directives + for py_file in sorted(src.rglob('*.py')): + parts = py_file.relative_to(src).with_suffix('').parts + + # Skip __pycache__, __init__, and dirs with hyphens (not valid Python identifiers) + if any(p.startswith('__') for p in parts): + continue + if any(not re.match(r'^[A-Za-z_][A-Za-z0-9_]*$', p) for p in parts): + continue + + module_path = '.'.join(parts) + md_path = docs_ref.joinpath(*parts).with_suffix('.md') + md_path.parent.mkdir(parents=True, exist_ok=True) + md_path.write_text(f'::: {module_path}\n') + " - name: Build site run: zensical build --clean diff --git a/docs/api-reference-guide.md b/docs/api-reference-guide.md new file mode 100644 index 00000000..7e6e5ef6 --- /dev/null +++ b/docs/api-reference-guide.md @@ -0,0 +1,599 @@ +# API Reference Documentation Guide + +This guide explains how to write Python docstrings in the Microbots project so that +the API reference documentation is generated correctly. Microbots uses +[mkdocstrings](https://mkdocstrings.github.io/) with the **NumPy docstring style** +to auto-generate API docs from source code. + +> **Key Rule:** Write proper NumPy-style docstrings in your Python code. The +> documentation is generated directly from these docstrings — no manual markdown +> files are needed for API reference. + +--- + +## Docstring Style: NumPy + +All docstrings in this project **must** follow the +[NumPy docstring format](https://numpydoc.readthedocs.io/en/latest/format.html). + +### Indentation Rules + +This is the most common source of rendering issues. After a section header +(`Parameters`, `Attributes`, `Returns`, etc.): + +- Parameter names must be at the **same indentation level** as the section header. +- Descriptions must be indented **one level deeper** than the parameter name. + +```python +# ✅ CORRECT — parameter names aligned with section header +def my_function(name: str, count: int): + """ + Do something useful. + + Parameters + ---------- + name : str + The name to use. + count : int + How many times to repeat. + """ + +# ❌ WRONG — extra indent on parameter names +def my_function(name: str, count: int): + """ + Do something useful. + + Parameters + ---------- + name : str + The name to use. + count : int + How many times to repeat. + """ +``` + +**Correct indentation renders as:** + +> **Parameters:** +> +> | Name | Type | Description | +> |------|------|-------------| +> | `name` | `str` | The name to use. | +> | `count` | `int` | How many times to repeat. | + +**Wrong indentation renders as:** + +> **Parameters:** +> +> | Name | Type | Description | +> |------|------|-------------| +> | `name` | `str` | The name to use. count : int How many times to repeat. | +> +> *(Everything collapses into a single parameter's description!)* + +The wrong indentation causes mkdocstrings to treat everything after the first +parameter as part of that parameter's description, resulting in a single wall of +text in the rendered docs. + +--- + +## Classes + +### Basic Class with Attributes + +Use the `Attributes` section in the **class docstring** to document instance +attributes. Each attribute follows the format `name : type`. + +```python +from enum import StrEnum + + +class ModelProvider(StrEnum): + """ + Supported LLM provider backends. + + Attributes + ---------- + OPENAI : str + Azure OpenAI provider. + OLLAMA_LOCAL : str + Local Ollama instance. + ANTHROPIC : str + Anthropic Claude provider. + """ + + OPENAI = "azure-openai" + OLLAMA_LOCAL = "ollama-local" + ANTHROPIC = "anthropic" +``` + +**Renders as:** + +> #### class `ModelProvider` +> *Bases:* `StrEnum` +> +> Supported LLM provider backends. +> +> **Attributes:** +> +> | Name | Type | Description | +> |------|------|-------------| +> | `OPENAI` | `str` | Azure OpenAI provider. | +> | `OLLAMA_LOCAL` | `str` | Local Ollama instance. | +> | `ANTHROPIC` | `str` | Anthropic Claude provider. | + +### Dataclass + +For `@dataclass` classes, document fields in the `Attributes` section of the +class docstring. + +```python +from dataclasses import dataclass +from pathlib import Path + + +@dataclass +class Mount: + """ + Folder mount configuration for a microbot environment. + + All the folders and files to be presented for the Bot should be + either mounted or copied to the Bot's sandbox environment using + this class. + + Attributes + ---------- + host_path : str + The absolute path on the host machine to be mounted or copied. + sandbox_path : str + The absolute path inside the Bot's sandbox environment where the + host_path will be mounted or copied. + permission : PermissionLabels + The permission level for the mounted/copied folder. + mount_type : MountType + The type of mount operation. Default is ``MountType.MOUNT``. + """ + + host_path: str + sandbox_path: str + permission: PermissionLabels + mount_type: MountType = MountType.MOUNT +``` + +**Renders as:** + +> #### class `Mount` +> *dataclass* +> +> Folder mount configuration for a microbot environment. +> +> All the folders and files to be presented for the Bot should be either mounted or copied to the Bot's sandbox environment using this class. +> +> **Attributes:** +> +> | Name | Type | Description | +> |------|------|-------------| +> | `host_path` | `str` | The absolute path on the host machine to be mounted or copied. | +> | `sandbox_path` | `str` | The absolute path inside the Bot's sandbox environment where the host_path will be mounted or copied. | +> | `permission` | `PermissionLabels` | The permission level for the mounted/copied folder. | +> | `mount_type` | `MountType` | The type of mount operation. Default is `MountType.MOUNT`. | + +### Class with `__init__` Parameters + +When a class has a non-trivial `__init__`, document **constructor parameters** +in the `__init__` docstring using `Parameters`, and document **public +attributes** in the class-level docstring using `Attributes`. + +#### Why both `Attributes` and `Parameters`? + +They serve different purposes in the documentation: + +| | **Attributes** (class docstring) | **Parameters** (\_\_init\_\_ docstring) | +|---|---|---| +| **Purpose** | Documents what the object **has** after creation | Documents what the constructor **accepts** to create the object | +| **Audience** | Users who already have an instance and want to access its properties | Users who need to know how to **create** an instance | +| **Includes** | All public instance attributes, including computed or derived ones set in `__init__` or `__post_init__` | Only the arguments passed to the constructor | +| **Shows defaults** | No | Yes — the Default column shows each parameter's default value | +| **Location** | Class-level docstring (top of the class) | `__init__` method docstring | + +**When are both needed?** + +- A class may have **attributes that are not constructor parameters** (e.g., `iteration_count` is initialized internally but never passed in). +- A constructor may have **parameters that don't become attributes** (e.g., a `token_provider` that is consumed during init but not stored). +- The **descriptions differ** — Attributes describe what the property represents on the object, while Parameters describe what to pass and what happens with each value. + +**When is only one needed?** + +- **Dataclasses / simple classes:** If every constructor argument maps directly to an attribute with the same meaning, you can use just `Attributes` in the class docstring. mkdocstrings will pick up the fields automatically. +- **Functions / methods:** Only use `Parameters` (there are no attributes). + +```python +class MicroBot: + """ + The core Microbot class. + + MicroBot is the core class representing the autonomous agent. + Other bots are extensions of this class. + + Attributes + ---------- + model : str + The model to use for the bot. + bot_type : BotType + The type of bot being created. + system_prompt : Optional[str] + The system prompt to guide the bot's behavior. + environment : Optional[any] + The execution environment for the bot. + """ + + def __init__( + self, + model: str, + bot_type: BotType = BotType.CUSTOM_BOT, + system_prompt: Optional[str] = None, + environment: Optional[any] = None, + ): + """ + Initialize a MicroBot instance. + + Parameters + ---------- + model : str + The model to use, in the format ``/``. + bot_type : BotType + The type of bot. Default is ``BotType.CUSTOM_BOT``. + system_prompt : Optional[str] + System prompt to guide behavior. Defaults to None. + environment : Optional[any] + The execution environment. If not provided, a default + LocalDockerEnvironment will be created. + """ + self.model = model + self.bot_type = bot_type +``` + +**Renders as:** + +> #### class `MicroBot` +> +> The core Microbot class. +> +> MicroBot is the core class representing the autonomous agent. Other bots are extensions of this class. +> +> **Attributes:** +> +> | Name | Type | Description | +> |------|------|-------------| +> | `model` | `str` | The model to use for the bot. | +> | `bot_type` | `BotType` | The type of bot being created. | +> | `system_prompt` | `Optional[str]` | The system prompt to guide the bot's behavior. | +> | `environment` | `Optional[any]` | The execution environment for the bot. | +> +> Initialize a MicroBot instance. +> +> **Parameters:** +> +> | Name | Type | Description | Default | +> |------|------|-------------|---------| +> | `model` | `str` | The model to use, in the format `/`. | *required* | +> | `bot_type` | `BotType` | The type of bot. | `BotType.CUSTOM_BOT` | +> | `system_prompt` | `Optional[str]` | System prompt to guide behavior. | `None` | +> | `environment` | `Optional[any]` | The execution environment. If not provided, a default LocalDockerEnvironment will be created. | `None` | + +> **Tip:** The `merge_init_into_class` option is enabled, so `__init__` +> parameters will appear on the same page as the class documentation. + +--- + +## Functions and Methods + +### Function with Parameters and Return Value + +```python +def get_free_port() -> int: + """ + Find and return an available TCP port on localhost. + + Scans for a free port by binding to port 0 and letting the OS + assign one. + + Returns + ------- + int + An available port number. + """ +``` + +**Renders as:** + +> #### function `get_free_port() → int` +> +> Find and return an available TCP port on localhost. +> +> Scans for a free port by binding to port 0 and letting the OS assign one. +> +> **Returns:** +> +> | Type | Description | +> |------|-------------| +> | `int` | An available port number. | + +### Method with Parameters, Returns, and Raises + +```python +def execute(self, command: str, timeout: Optional[int] = 300) -> CmdReturn: + """ + Execute a shell command inside the environment. + + Parameters + ---------- + command : str + The shell command to execute. + timeout : Optional[int] + Maximum seconds to wait for the command to complete. + Defaults to 300. + + Returns + ------- + CmdReturn + An object containing stdout, stderr, and return_code. + + Raises + ------ + TimeoutError + If the command exceeds the timeout duration. + ConnectionError + If the environment is not running. + """ +``` + +**Renders as:** + +> #### method `execute(command, timeout=300) → CmdReturn` +> +> Execute a shell command inside the environment. +> +> **Parameters:** +> +> | Name | Type | Description | Default | +> |------|------|-------------|---------| +> | `command` | `str` | The shell command to execute. | *required* | +> | `timeout` | `Optional[int]` | Maximum seconds to wait for the command to complete. | `300` | +> +> **Returns:** +> +> | Type | Description | +> |------|-------------| +> | `CmdReturn` | An object containing stdout, stderr, and return_code. | +> +> **Raises:** +> +> | Type | Description | +> |------|-------------| +> | `TimeoutError` | If the command exceeds the timeout duration. | +> | `ConnectionError` | If the environment is not running. | + +--- + +## Abstract Base Classes + +Use the same docstring conventions. mkdocstrings will display the class +with its abstract methods. + +```python +from abc import ABC, abstractmethod + + +class Environment(ABC): + """ + Abstract base class for all execution environments. + + Subclasses must implement ``start``, ``stop``, and ``execute``. + """ + + @abstractmethod + def start(self): + """Start the environment.""" + + @abstractmethod + def stop(self): + """Stop and clean up the environment.""" + + @abstractmethod + def execute(self, command: str) -> CmdReturn: + """ + Execute a command in the environment. + + Parameters + ---------- + command : str + The command to run. + + Returns + ------- + CmdReturn + The command result. + """ +``` + +**Renders as:** + +> #### class `Environment` +> *Bases:* `ABC` +> +> Abstract base class for all execution environments. +> +> Subclasses must implement `start`, `stop`, and `execute`. +> +> --- +> +> ##### method `start()` · *abstract* +> Start the environment. +> +> ##### method `stop()` · *abstract* +> Stop and clean up the environment. +> +> ##### method `execute(command) → CmdReturn` · *abstract* +> Execute a command in the environment. +> +> **Parameters:** +> +> | Name | Type | Description | +> |------|------|-------------| +> | `command` | `str` | The command to run. | +> +> **Returns:** +> +> | Type | Description | +> |------|-------------| +> | `CmdReturn` | The command result. | + +--- + +## Enums + +Document each member in the `Attributes` section. + +```python +from enum import StrEnum + + +class BotType(StrEnum): + """ + Types of bots available in the Microbots framework. + + Attributes + ---------- + READING_BOT : str + A bot specialized in reading and comprehending code. + WRITING_BOT : str + A bot that can make controlled file edits. + BROWSING_BOT : str + A bot with web browsing capabilities. + CUSTOM_BOT : str + A general-purpose custom bot. + """ + + READING_BOT = "READING_BOT" + WRITING_BOT = "WRITING_BOT" + BROWSING_BOT = "BROWSING_BOT" + CUSTOM_BOT = "CUSTOM_BOT" +``` + +**Renders as:** + +> #### class `BotType` +> *Bases:* `StrEnum` +> +> Types of bots available in the Microbots framework. +> +> **Attributes:** +> +> | Name | Type | Description | +> |------|------|-------------| +> | `READING_BOT` | `str` | A bot specialized in reading and comprehending code. | +> | `WRITING_BOT` | `str` | A bot that can make controlled file edits. | +> | `BROWSING_BOT` | `str` | A bot with web browsing capabilities. | +> | `CUSTOM_BOT` | `str` | A general-purpose custom bot. | + +--- + +## Module-Level Constants + +Module-level variables are documented with an inline comment or a docstring +immediately following the assignment. + +```python +WORKING_DIR = str(Path.home() / "MICROBOTS_WORKDIR") +"""Default working directory on the host machine.""" + +DOCKER_WORKING_DIR = "/workdir" +"""Working directory inside the Docker container.""" +``` + +**Renders as:** + +> **module-attribute** `WORKING_DIR = str(Path.home() / "MICROBOTS_WORKDIR")` +> +> Default working directory on the host machine. +> +> --- +> +> **module-attribute** `DOCKER_WORKING_DIR = "/workdir"` +> +> Working directory inside the Docker container. + +--- + +## Available Sections + +The following section headers are recognized by mkdocstrings (NumPy style): + +| Section | Use for | +|----------------|----------------------------------------------| +| `Parameters` | Function/method arguments | +| `Attributes` | Class or instance attributes | +| `Returns` | Return values | +| `Yields` | Values yielded by generators | +| `Raises` | Exceptions that may be raised | +| `Notes` | Additional implementation notes | +| `Examples` | Usage examples (rendered as code blocks) | +| `See Also` | Cross-references to related objects | +| `References` | Citations or external links | +| `Warnings` | Important warnings for users | + +Each section header must be followed by a line of dashes of equal length: + +``` +Parameters +---------- +``` + +--- + +## Cross-Referencing Other Classes + +You can link to any documented class, method, or function from within a +docstring using backtick references. mkdocstrings with autorefs will +automatically resolve these. + +```python +class ReadingBot(MicroBot): + """ + A bot specialized in reading and comprehending code. + + Extends `MicroBot` with read-only permissions. + See `Mount` for folder configuration details. + """ +``` + +In standalone markdown files (guides, blogs), use bracket syntax: + +```markdown +See the [MicroBot][microbots.MicroBot.MicroBot] class for details. +Configure folders with [Mount][microbots.extras.mount.Mount]. +``` + +--- + +## Quick Checklist + +Before submitting a PR, verify your docstrings follow these rules: + +- [ ] **NumPy style** — Use `Parameters`, `Attributes`, `Returns`, etc. with dashed underlines +- [ ] **Correct indentation** — Parameter names at the same indent as the section header +- [ ] **Type annotations** — Include types in both the signature and the docstring (`name : str`) +- [ ] **All public members documented** — Every public class, method, and function has a docstring +- [ ] **Module-level variables** — Have a docstring on the line immediately after assignment +- [ ] **No bare code blocks** — Descriptions should be prose, not raw code dumps +- [ ] **Cross-references** — Use backticks around class/function names to enable auto-linking + +--- + +## How It Works + +1. Each Python module has a corresponding `.md` stub file in `docs/api-reference/` containing only a mkdocstrings directive (e.g., `::: microbots.MicroBot`) +2. During `zensical build`, mkdocstrings reads the source code and docstrings +3. It generates fully rendered HTML documentation with class hierarchies, parameter tables, source code links, and cross-references +4. The CI pipeline in `.github/workflows/pages.yml` auto-generates stub files for any new Python modules before building diff --git a/docs/api-reference/microbots/MicroBot.md b/docs/api-reference/microbots/MicroBot.md new file mode 100644 index 00000000..9e593ddb --- /dev/null +++ b/docs/api-reference/microbots/MicroBot.md @@ -0,0 +1,5 @@ +::: microbots.MicroBot + options: + filters: + - "!^system_prompt_common$" + - "!^logger$" diff --git a/docs/api-reference/microbots/bot/AgentBoss.md b/docs/api-reference/microbots/bot/AgentBoss.md new file mode 100644 index 00000000..3f38fc2f --- /dev/null +++ b/docs/api-reference/microbots/bot/AgentBoss.md @@ -0,0 +1 @@ +::: microbots.bot.AgentBoss diff --git a/docs/api-reference/microbots/bot/BrowsingBot.md b/docs/api-reference/microbots/bot/BrowsingBot.md new file mode 100644 index 00000000..7a632b31 --- /dev/null +++ b/docs/api-reference/microbots/bot/BrowsingBot.md @@ -0,0 +1 @@ +::: microbots.bot.BrowsingBot diff --git a/docs/api-reference/microbots/bot/CopilotBot.md b/docs/api-reference/microbots/bot/CopilotBot.md new file mode 100644 index 00000000..9557e235 --- /dev/null +++ b/docs/api-reference/microbots/bot/CopilotBot.md @@ -0,0 +1 @@ +::: microbots.bot.CopilotBot diff --git a/docs/api-reference/microbots/bot/LogAnalysisBot.md b/docs/api-reference/microbots/bot/LogAnalysisBot.md new file mode 100644 index 00000000..dea1d0e3 --- /dev/null +++ b/docs/api-reference/microbots/bot/LogAnalysisBot.md @@ -0,0 +1 @@ +::: microbots.bot.LogAnalysisBot diff --git a/docs/api-reference/microbots/bot/ReadingBot.md b/docs/api-reference/microbots/bot/ReadingBot.md new file mode 100644 index 00000000..92de2072 --- /dev/null +++ b/docs/api-reference/microbots/bot/ReadingBot.md @@ -0,0 +1 @@ +::: microbots.bot.ReadingBot diff --git a/docs/api-reference/microbots/bot/WritingBot.md b/docs/api-reference/microbots/bot/WritingBot.md new file mode 100644 index 00000000..2a90ad51 --- /dev/null +++ b/docs/api-reference/microbots/bot/WritingBot.md @@ -0,0 +1 @@ +::: microbots.bot.WritingBot diff --git a/docs/api-reference/microbots/constants.md b/docs/api-reference/microbots/constants.md new file mode 100644 index 00000000..375cfaea --- /dev/null +++ b/docs/api-reference/microbots/constants.md @@ -0,0 +1 @@ +::: microbots.constants diff --git a/docs/api-reference/microbots/environment/Environment.md b/docs/api-reference/microbots/environment/Environment.md new file mode 100644 index 00000000..75ea4b26 --- /dev/null +++ b/docs/api-reference/microbots/environment/Environment.md @@ -0,0 +1 @@ +::: microbots.environment.Environment diff --git a/docs/api-reference/microbots/environment/local_docker/LocalDockerEnvironment.md b/docs/api-reference/microbots/environment/local_docker/LocalDockerEnvironment.md new file mode 100644 index 00000000..1d96f1e9 --- /dev/null +++ b/docs/api-reference/microbots/environment/local_docker/LocalDockerEnvironment.md @@ -0,0 +1 @@ +::: microbots.environment.local_docker.LocalDockerEnvironment diff --git a/docs/api-reference/microbots/environment/local_docker/image_builder/ShellCommunicator.md b/docs/api-reference/microbots/environment/local_docker/image_builder/ShellCommunicator.md new file mode 100644 index 00000000..a36aeb42 --- /dev/null +++ b/docs/api-reference/microbots/environment/local_docker/image_builder/ShellCommunicator.md @@ -0,0 +1 @@ +::: microbots.environment.local_docker.image_builder.ShellCommunicator diff --git a/docs/api-reference/microbots/environment/local_docker/image_builder/dockerShell.md b/docs/api-reference/microbots/environment/local_docker/image_builder/dockerShell.md new file mode 100644 index 00000000..4a5a8bcd --- /dev/null +++ b/docs/api-reference/microbots/environment/local_docker/image_builder/dockerShell.md @@ -0,0 +1 @@ +::: microbots.environment.local_docker.image_builder.dockerShell diff --git a/docs/api-reference/microbots/extras/mount.md b/docs/api-reference/microbots/extras/mount.md new file mode 100644 index 00000000..4e307a17 --- /dev/null +++ b/docs/api-reference/microbots/extras/mount.md @@ -0,0 +1 @@ +::: microbots.extras.mount diff --git a/docs/api-reference/microbots/index.md b/docs/api-reference/microbots/index.md new file mode 100644 index 00000000..3a6a98b2 --- /dev/null +++ b/docs/api-reference/microbots/index.md @@ -0,0 +1 @@ +::: microbots diff --git a/docs/api-reference/microbots/llm/anthropic_api.md b/docs/api-reference/microbots/llm/anthropic_api.md new file mode 100644 index 00000000..e94f901c --- /dev/null +++ b/docs/api-reference/microbots/llm/anthropic_api.md @@ -0,0 +1 @@ +::: microbots.llm.anthropic_api diff --git a/docs/api-reference/microbots/llm/llm.md b/docs/api-reference/microbots/llm/llm.md new file mode 100644 index 00000000..e1e192b9 --- /dev/null +++ b/docs/api-reference/microbots/llm/llm.md @@ -0,0 +1 @@ +::: microbots.llm.llm diff --git a/docs/api-reference/microbots/llm/ollama_local.md b/docs/api-reference/microbots/llm/ollama_local.md new file mode 100644 index 00000000..e9fd2a39 --- /dev/null +++ b/docs/api-reference/microbots/llm/ollama_local.md @@ -0,0 +1 @@ +::: microbots.llm.ollama_local diff --git a/docs/api-reference/microbots/llm/openai_api.md b/docs/api-reference/microbots/llm/openai_api.md new file mode 100644 index 00000000..a8eda04b --- /dev/null +++ b/docs/api-reference/microbots/llm/openai_api.md @@ -0,0 +1 @@ +::: microbots.llm.openai_api diff --git a/docs/api-reference/microbots/tools/external_tool.md b/docs/api-reference/microbots/tools/external_tool.md new file mode 100644 index 00000000..00b72509 --- /dev/null +++ b/docs/api-reference/microbots/tools/external_tool.md @@ -0,0 +1 @@ +::: microbots.tools.external_tool diff --git a/docs/api-reference/microbots/tools/internal_tool.md b/docs/api-reference/microbots/tools/internal_tool.md new file mode 100644 index 00000000..9d028387 --- /dev/null +++ b/docs/api-reference/microbots/tools/internal_tool.md @@ -0,0 +1 @@ +::: microbots.tools.internal_tool diff --git a/docs/api-reference/microbots/tools/tool.md b/docs/api-reference/microbots/tools/tool.md new file mode 100644 index 00000000..2bbf1903 --- /dev/null +++ b/docs/api-reference/microbots/tools/tool.md @@ -0,0 +1 @@ +::: microbots.tools.tool diff --git a/docs/api-reference/microbots/tools/tool_definitions/memory_tool.md b/docs/api-reference/microbots/tools/tool_definitions/memory_tool.md new file mode 100644 index 00000000..55389acd --- /dev/null +++ b/docs/api-reference/microbots/tools/tool_definitions/memory_tool.md @@ -0,0 +1 @@ +::: microbots.tools.tool_definitions.memory_tool diff --git a/docs/api-reference/microbots/tools/tool_definitions/microbot_sub_agent.md b/docs/api-reference/microbots/tools/tool_definitions/microbot_sub_agent.md new file mode 100644 index 00000000..9b6f3cb2 --- /dev/null +++ b/docs/api-reference/microbots/tools/tool_definitions/microbot_sub_agent.md @@ -0,0 +1 @@ +::: microbots.tools.tool_definitions.microbot_sub_agent diff --git a/docs/api-reference/microbots/tools/tool_yaml_parser.md b/docs/api-reference/microbots/tools/tool_yaml_parser.md new file mode 100644 index 00000000..2b72832c --- /dev/null +++ b/docs/api-reference/microbots/tools/tool_yaml_parser.md @@ -0,0 +1 @@ +::: microbots.tools.tool_yaml_parser diff --git a/docs/api-reference/microbots/utils/copilot_auth.md b/docs/api-reference/microbots/utils/copilot_auth.md new file mode 100644 index 00000000..777e5b0e --- /dev/null +++ b/docs/api-reference/microbots/utils/copilot_auth.md @@ -0,0 +1 @@ +::: microbots.utils.copilot_auth diff --git a/docs/api-reference/microbots/utils/logger.md b/docs/api-reference/microbots/utils/logger.md new file mode 100644 index 00000000..72dfaae9 --- /dev/null +++ b/docs/api-reference/microbots/utils/logger.md @@ -0,0 +1 @@ +::: microbots.utils.logger diff --git a/docs/api-reference/microbots/utils/multi_agent_log_parser.md b/docs/api-reference/microbots/utils/multi_agent_log_parser.md new file mode 100644 index 00000000..5cdf6a5d --- /dev/null +++ b/docs/api-reference/microbots/utils/multi_agent_log_parser.md @@ -0,0 +1 @@ +::: microbots.utils.multi_agent_log_parser diff --git a/docs/api-reference/microbots/utils/network.md b/docs/api-reference/microbots/utils/network.md new file mode 100644 index 00000000..7e5182de --- /dev/null +++ b/docs/api-reference/microbots/utils/network.md @@ -0,0 +1 @@ +::: microbots.utils.network diff --git a/docs/api-reference/microbots/utils/path.md b/docs/api-reference/microbots/utils/path.md new file mode 100644 index 00000000..ecedecbc --- /dev/null +++ b/docs/api-reference/microbots/utils/path.md @@ -0,0 +1 @@ +::: microbots.utils.path diff --git a/docs/javascripts/doc-anchors.js b/docs/javascripts/doc-anchors.js new file mode 100644 index 00000000..8e97c4e6 --- /dev/null +++ b/docs/javascripts/doc-anchors.js @@ -0,0 +1,15 @@ +// Make API reference doc headings clickable permalink anchors +document.addEventListener("DOMContentLoaded", function () { + document.querySelectorAll(".doc.doc-heading[id]").forEach(function (heading) { + heading.style.cursor = "pointer"; + heading.addEventListener("click", function (e) { + e.preventDefault(); + e.stopPropagation(); + var id = heading.getAttribute("id"); + // Update URL hash + history.pushState(null, "", "#" + id); + // Scroll to element + heading.scrollIntoView({ behavior: "smooth", block: "start" }); + }); + }); +}); diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 7a391b5f..cd9e94d4 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -137,3 +137,35 @@ .lightbox-close:hover { opacity: 1; } + +/* API Reference - permalink anchors on doc headings */ +.doc.doc-heading { + position: relative; +} + +.doc.doc-heading::after { + content: "¶"; + margin-left: 0.5em; + opacity: 0; + font-size: 0.7em; + color: var(--md-accent-fg-color, #526cfe); + transition: opacity 0.2s; + cursor: pointer; +} + +.doc.doc-heading:hover::after { + opacity: 0.6; +} + +.doc.doc-heading:hover::after:hover { + opacity: 1; +} + +/* Make doc headings themselves clickable anchor links */ +.doc.doc-heading { + cursor: pointer; +} + +.doc.doc-heading code { + cursor: pointer; +} diff --git a/mkdocs.yml b/mkdocs.yml index e4eca852..34a415df 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -22,13 +22,33 @@ theme: icon: material/brightness-4 name: Switch to light mode features: - - navigation.instant - - navigation.sections - navigation.top - navigation.tabs - content.code.copy +plugins: + - search + - mkdocstrings: + handlers: + python: + paths: [src] + options: + show_source: true + show_root_heading: true + show_symbol_type_heading: true + show_symbol_type_toc: true + members_order: alphabetical + docstring_style: numpy + show_if_no_docstring: true + show_labels: true + show_bases: true + show_signature: true + show_signature_annotations: true + merge_init_into_class: true + markdown_extensions: + - toc: + permalink: true - pymdownx.highlight: anchor_linenums: true - pymdownx.superfences @@ -50,9 +70,49 @@ nav: - Blogs: - blog/index.md - "Microbots : Safety First Agentic Workflow": blog/microbots-safety-first-ai-agent.md + - API Reference: + - MicroBot: api-reference/microbots/MicroBot.md + - bot: + - AgentBoss: api-reference/microbots/bot/AgentBoss.md + - BrowsingBot: api-reference/microbots/bot/BrowsingBot.md + - CopilotBot: api-reference/microbots/bot/CopilotBot.md + - LogAnalysisBot: api-reference/microbots/bot/LogAnalysisBot.md + - ReadingBot: api-reference/microbots/bot/ReadingBot.md + - WritingBot: api-reference/microbots/bot/WritingBot.md + - environment: + - Environment: api-reference/microbots/environment/Environment.md + - local_docker: + - LocalDockerEnvironment: api-reference/microbots/environment/local_docker/LocalDockerEnvironment.md + - image_builder: + - dockerShell: api-reference/microbots/environment/local_docker/image_builder/dockerShell.md + - ShellCommunicator: api-reference/microbots/environment/local_docker/image_builder/ShellCommunicator.md + - extras: + - mount: api-reference/microbots/extras/mount.md + - llm: + - anthropic_api: api-reference/microbots/llm/anthropic_api.md + - llm: api-reference/microbots/llm/llm.md + - ollama_local: api-reference/microbots/llm/ollama_local.md + - openai_api: api-reference/microbots/llm/openai_api.md + - tools: + - external_tool: api-reference/microbots/tools/external_tool.md + - internal_tool: api-reference/microbots/tools/internal_tool.md + - tool: api-reference/microbots/tools/tool.md + - tool_yaml_parser: api-reference/microbots/tools/tool_yaml_parser.md + - tool_definitions: + - memory_tool: api-reference/microbots/tools/tool_definitions/memory_tool.md + - microbot_sub_agent: api-reference/microbots/tools/tool_definitions/microbot_sub_agent.md + - utils: + - copilot_auth: api-reference/microbots/utils/copilot_auth.md + - logger: api-reference/microbots/utils/logger.md + - multi_agent_log_parser: api-reference/microbots/utils/multi_agent_log_parser.md + - network: api-reference/microbots/utils/network.md + - path: api-reference/microbots/utils/path.md + - constants: api-reference/microbots/constants.md + - "Docstring Guide": api-reference-guide.md extra_css: - stylesheets/extra.css extra_javascript: - javascripts/lightbox.js + - javascripts/doc-anchors.js diff --git a/src/microbots/environment/__init__.py b/src/microbots/environment/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/src/microbots/environment/local_docker/image_builder/__init__.py b/src/microbots/environment/local_docker/image_builder/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/src/microbots/tools/__init__.py b/src/microbots/tools/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/src/microbots/utils/__init__.py b/src/microbots/utils/__init__.py new file mode 100644 index 00000000..e69de29b From e7827f2612ddad8610943a904eaa6a4fb2db4e5e Mon Sep 17 00:00:00 2001 From: shivashanmugam Date: Sat, 25 Apr 2026 14:07:13 +0530 Subject: [PATCH 2/3] remove autogenerate md files script from pages.yml Co-authored-by: Copilot --- .github/workflows/pages.yml | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 5e201fe4..73e3b14c 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -29,31 +29,6 @@ jobs: - name: Install Zensical and plugins run: pip install zensical mkdocstrings[python] - - name: Generate API reference stubs - run: | - python -c " - import os, re - from pathlib import Path - - src = Path('src') - docs_ref = Path('docs/api-reference') - - # Walk source tree and create stub md files with mkdocstrings directives - for py_file in sorted(src.rglob('*.py')): - parts = py_file.relative_to(src).with_suffix('').parts - - # Skip __pycache__, __init__, and dirs with hyphens (not valid Python identifiers) - if any(p.startswith('__') for p in parts): - continue - if any(not re.match(r'^[A-Za-z_][A-Za-z0-9_]*$', p) for p in parts): - continue - - module_path = '.'.join(parts) - md_path = docs_ref.joinpath(*parts).with_suffix('.md') - md_path.parent.mkdir(parents=True, exist_ok=True) - md_path.write_text(f'::: {module_path}\n') - " - - name: Build site run: zensical build --clean From d75c462365c51beee9a9af464e0043ed15025567 Mon Sep 17 00:00:00 2001 From: shivashanmugam Date: Sat, 25 Apr 2026 14:08:08 +0530 Subject: [PATCH 3/3] remove filters from `microbot.md` --- docs/api-reference/microbots/MicroBot.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/api-reference/microbots/MicroBot.md b/docs/api-reference/microbots/MicroBot.md index 9e593ddb..3759b1e6 100644 --- a/docs/api-reference/microbots/MicroBot.md +++ b/docs/api-reference/microbots/MicroBot.md @@ -1,5 +1 @@ -::: microbots.MicroBot - options: - filters: - - "!^system_prompt_common$" - - "!^logger$" +::: microbots.MicroBot \ No newline at end of file