From 2d78040cf928d9531087a521094a996632b0c7bf Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Thu, 2 Apr 2026 18:20:45 +0200 Subject: [PATCH] Auto-generate docs pages from README: About & Features --- README.md | 1 - docs/01-about/.gitignore | 5 +- docs/01-about/000_intro.md | 101 ------------------------------------- docs/autogen_docs.py | 35 +++++++++++++ 4 files changed, 39 insertions(+), 103 deletions(-) delete mode 100644 docs/01-about/000_intro.md diff --git a/README.md b/README.md index 7d1d1ae1..feba7f7b 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,6 @@

Serena is the IDE for your coding agent. -

* Serena provides essential **semantic code retrieval, editing and refactoring tools** that are akin to an IDE's capabilities, diff --git a/docs/01-about/.gitignore b/docs/01-about/.gitignore index e1fbb867..463af074 100644 --- a/docs/01-about/.gitignore +++ b/docs/01-about/.gitignore @@ -1 +1,4 @@ -/035_tools.md \ No newline at end of file +# auto-generated files +/000_intro.md +/005_features.md +/035_tools.md diff --git a/docs/01-about/000_intro.md b/docs/01-about/000_intro.md deleted file mode 100644 index c1b9de6b..00000000 --- a/docs/01-about/000_intro.md +++ /dev/null @@ -1,101 +0,0 @@ -# About Serena - -Serena is **the IDE for your coding agent**. - -* It provides essential **semantic code retrieval, editing and refactoring tools** that are akin to an IDE's capabilities, - operating at the symbol level and exploiting relational structure. -* It integrates with any client/LLM via the model context protocol (MCP). - -Serena's agent-first tool design involves robust high-level abstractions, distinguishing it from -approaches that rely on low-level concepts like line numbers or primitive search patterns. - -Practically, this means that your agent operates faster, more efficiently and more reliably, especially in larger and -more complex codebases. - -## Features - -Serena supports two code intelligence backends: - -* **Language servers** implementing the language server protocol (LSP) — the free/open-source alternative. -* **The Serena JetBrains Plugin**, which leverages the capabilities of your JetBrains IDE. - -Language Servers, while very powerful, have inherent limitations. -The JetBrains variant is the more advanced solution, as detailed below. It is also more memory-efficient, especially in -multi-agent scenarios. - - -Purchasing the JetBrains plugin supports the continued development of Serena. - - -### Retrieval - -Serena's retrieval tools allow agents to explore codebases at the symbol level, understanding structure and relationships -without reading entire files. - -| Capability | Language Server | JetBrains Plugin | -|------------------------------------|-----------------|------------------| -| **find symbol** | yes | yes | -| **symbol overview** (file outline) | yes | yes | -| **find referencing symbols** | yes | yes | -| **search in project dependencies** | -- | yes | -| **type hierarchy** | -- | yes | -| **find declaration** | -- | yes | -| **find implementations** | -- | yes | -| **query external projects** | yes | yes | - - -### Refactoring - -| Capability | Language Server | JetBrains Plugin | -|----------------------------------------------|--------------------|-----------------------------------| -| **rename** | yes (only symbols) | yes (symbols, files, directories) | -| **move** (symbol, file, directory) | -- | yes | -| **inline** | -- | yes | -| **propagate deletions** (remove unused code) | -- | yes | - - -### Symbolic Editing - -Much more token-efficient than default editing tools. - -| Capability | Language Server | JetBrains Plugin | -|--------------------------|-----------------|------------------| -| **replace symbol body** | yes | yes | -| **insert after symbol** | yes | yes | -| **insert before symbol** | yes | yes | -| **safe delete** | yes | yes | - -### Basic Features - -Beyond its semantic capabilities, Serena includes a set of basic utilities for completeness. -When Serena is used inside an agentic harness such as Claude Code or Codex, these tools are typically disabled by default, -since the surrounding harness already provides overlapping file, search, and shell capabilities. - -- **`search_for_pattern`** -- Flexible regex search across the codebase with glob-based file filtering, context lines, - and the option to restrict to code files only. Useful when you don't know the exact symbol name. -- **`list_dir` / `find_file`** -- Directory listing and file search with glob support. Helps agents orient themselves - in unfamiliar projects. -- **`read_file`** -- Read files or file chunks by line range, for cases where symbolic access isn't applicable - (e.g. configuration files, HTML templates). -- **`execute_shell_command`** -- Run shell commands (builds, tests, linters) directly from the agent, - with configurable working directory and output limits. - -### Memory Management - -Serena provides the functionality of a fully featured agent, and a useful aspect of this is Serena's memory system. -Despite its simplicity, we received positive feedback from many users who tend to combine it with their -agent's internal memory management (e.g., `AGENTS.md` files). -Many other memory management systems for agents exist, and you can easily disable Serena's memory management if you -prefer not to use it. - -## Configurability - -Active tools, tool descriptions, prompts, language backend details and many other aspects of Serena -can be flexibly configured on a per-case basis by simply adjusting a few lines of YAML. -To achieve this, Serena offers multiple levels of (composable) configuration: - -* global configuration -* MCP launch command (CLI) configuration -* per-project configuration (with local overrides) -* execution context-specific configuration (e.g. for particular clients) -* dynamically composable configuration fragments (modes) diff --git a/docs/autogen_docs.py b/docs/autogen_docs.py index 5b4ca422..8c828809 100644 --- a/docs/autogen_docs.py +++ b/docs/autogen_docs.py @@ -1,5 +1,6 @@ import logging import os +import re import shutil from pathlib import Path from typing import Optional, List @@ -170,11 +171,45 @@ def autogen_tool_list(target_filename = "01-about/035_tools.md"): f.write(text.build()) +def autogen_about_intro_features(): + readme_path = Path(__file__).parent.parent / "README.md" + with open(readme_path, "r", encoding="utf-8") as f: + readme_contents = f.read() + + match = re.search(r"(.*?)(.*?)^(## Features.*?)^## ", readme_contents, re.DOTALL | re.MULTILINE) + assert match, f"Failed to extract about texts from README.md. {__file__} probably needs to be updated." + + tagline = match.group(1).strip() + about_text = match.group(2).strip() + features_text = match.group(3).strip() + + autogen_info = f"\n\n" + + with open(Path(__file__).parent / "01-about" / "000_intro.md", "w", encoding="utf-8") as f: + f.write(autogen_info) + f.write("# About Serena\n\n") + f.write(f"**{tagline}**\n\n") + f.write(f"{about_text}\n\n") + + jetbrains_marketplace_link = ('```{raw} html\n' + '

' + '' + '

\n```') + + with open(Path(__file__).parent / "01-about" / "005_features.md", "w", encoding="utf-8") as f: + f.write(autogen_info) + features_text = re.subn(r"^#", r"", features_text, flags=re.MULTILINE)[0] + features_text = re.sub(r'