bench get-app https://github.com/raisulislam0/frappe_doc

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=raisulislam0%2Ffrappe_doc)](https://frappegems.com/gems/apps/raisulislam0/frappe_doc)

📚 frappe_doc — The Developer Portal for Frappe & ERPNext

> Stop digging through source code. Stop guessing parameter names. Stop opening five browser tabs to understand one API call.
> frappe_doc gives you a live, searchable, interactive documentation portal — auto-generated from your actual codebase.

---

Table of Contents

• What is frappe_doc?
• Features at a Glance
• Installation
• Accessing the Portal
• API Explorer
  • How APIs Are Discovered
  • HTTP Method Inference
  • Searching & Filtering
  • Code Snippets (Frappe JS & cURL)
  • Try It Out
  • Refresh Cache
• Writing Great API Documentation
  • Python Type Hints (Automatic)
  • Google-Style Docstrings
  • Full Example — Best Practice API
  • Docstring Section Reference
• DocType Field Explorer
  • Hierarchical Child Tables
  • Field Search
• Access Control
• FAQ

---

What is frappe_doc?

frappe_doc is a zero-configuration developer portal that installs as a standard Frappe app.

The moment you install it, it: - Scans every installed app for all @frappe.whitelist() functions using Python's ast module — no code is imported or executed, so it's completely safe. - Parses docstrings to extract parameter descriptions, return types, and usage examples. - Extracts Python type annotations from your function signatures directly. - Renders an interactive UI in your Frappe desk at /app/developer_portal (or the shortcut /doc).

You get Swagger-like documentation — but built for the Frappe ecosystem, requiring zero extra configuration files, zero decorators beyond what you already use, and zero maintenance overhead.

---

Features at a Glance

Feature	Description
🔍 API Explorer	Browse, search, and filter all whitelisted endpoints across all installed apps
📝 Auto-parsed Docs	Docstrings, type hints, args, returns, and examples — rendered automatically
🧪 Try It Out	Send live API requests directly from the portal, see real responses
📋 Code Snippets	One-click frappe.call() and curl snippets ready to copy
🏗️ DocType Explorer	Browse all DocType fields with child table trees expanded hierarchically
⚡ Smart Caching	Results are cached for 1 hour; one click to refresh on demand
🔒 Safe & Secure	AST-only scanning (no execution), with role-based access control

---

Installation

# From your bench directory
cd /path/to/frappe-bench

# Get the app
bench get-app https://github.com/raisulislam0/frappe_doc.git

# Install on your site
bench --site yoursite.com install-app frappe_doc
bench --site yoursite.com migrate

# Clear cache to register the new page
bench --site yoursite.com clear-cache

---

Accessing the Portal

Once installed, any System Manager (or any logged-in user when developer_mode is enabled) can access the portal:

• Direct desk link: /app/developer_portal
• Short URL: /doc (redirects automatically)

The portal is divided into two main tabs:

1. API Explorer — Browse all @frappe.whitelist() endpoints
2. DocType Fields — Explore all DocType schemas with child-table trees

---

API Explorer

How APIs Are Discovered

frappe_doc automatically scans all installed apps using Python's ast module. It walks every .py file in every installed app and detects all functions decorated with:

@frappe.whitelist()
@frappe.whitelist(allow_guest=True)
@frappe.whitelist(methods=["GET"])
@whitelist()  # bare form also detected

No configuration needed. No registration required. If it's whitelisted, it's documented.

---

HTTP Method Inference

frappe_doc intelligently infers the expected HTTP method from your function name, even when you don't explicitly declare one:

Function Name Prefix	Inferred Method
get_, fetch_, find_, search_, list_, check_	GET
create_, save_, submit_, add_, insert_, post_	POST
update_, edit_, modify_, patch_	PUT (via POST)
delete_, remove_, cancel_, disable_	DELETE (via POST)

> Tip: Use explicit method declarations to override inference and get the most accurate documentation: > python > @frappe.whitelist(methods=["GET"]) > def get_employee_profile(employee_id: str) -> dict: > ... >

Inferred methods are shown with a ~ prefix (e.g., ~GET) and a dashed border to indicate they are guesses. Explicitly declared methods appear with solid badges.

---

Searching & Filtering

The search bar supports multiple scopes via a dropdown:

Scope	Searches In
All	Everything — route, args, docstring, file, app
App	The app name (e.g., erpnext, hrms)
Module	Full Python module path
Filename	Source file path
DocType	Detected associated DocType
Function	The function name only
Route	The full /api/method/... route
Args	Parameter names
Docstring	Content of the docstring

---

Code Snippets (Frappe JS & cURL)

Every API card has a Usage section (collapsed by default) that generates ready-to-use code snippets.

Frappe JS tab:

frappe.call({
    method: "hrms.api.leave.apply_for_leave",
    args: {
        employee: "",
        leave_type: "",
        from_date: "",
        to_date: "",
    },
    callback: function(r) {
        console.log(r.message);
    }
});

curl tab:

curl -X POST \
  "https://yoursite.com/api/method/hrms.api.leave.apply_for_leave" \
  -H "Authorization: token :" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "employee=EMP-001&leave_type=Casual+Leave&from_date=2024-01-01&to_date=2024-01-03"

Examples tab (shown if you document Example Request / Example Response in your docstring): Side-by-side JSON blocks showing request and response payloads.

---

Try It Out

Click the TRY IT OUT section on any API card to:

1. Fill in parameter values in an interactive form
2. Click ▶ Send Request to fire the real API call against your running site
3. Instantly see the JSON response with syntax highlighting
4. See the response time in milliseconds

If your docstring includes an Example Request section, the form fields are pre-filled with the example values automatically.

---

Refresh Cache

Scan results are cached for 1 hour. If you write a new API and want to see it immediately, click the Refresh Cache button in the API Explorer toolbar. It re-scans all apps and updates the cache.

---

Writing Great API Documentation

This is where the real magic happens. By following these conventions in your Python code, frappe_doc renders rich, professional documentation automatically — with no extra work.

---

Python Type Hints (Automatic)

frappe_doc reads Python 3 type annotations directly from your function signature. You do not need to repeat types in the docstring — they are detected automatically.

@frappe.whitelist()
def toggle_item(name: str, is_active: bool) -> dict:
    """Toggle the active state of an item."""
    ...

What frappe_doc renders:

• Parameter badges: name: str · is_active: bool
• Parameter table with Type column pre-filled: str, bool
• Returns section shows: dict

Supported types include all Python built-ins and complex annotations:

def get_items(
    filters: dict,
    limit: int = 20,
    fields: list | None = None,
) -> list[dict]:
    ...

These will render as dict, int, list | None, list[dict] in the portal.

---

Google-Style Docstrings

frappe_doc parses Google-style docstrings — the most readable and widely adopted Python docstring format.

Section Headers (Recognized)

Section Header	Alias(es)	Purpose
Args:	Arguments:, Parameters:, Params:	Document parameters
Returns:	Return:	Describe the return value
Raises:	—	Document exceptions
Example Request:	—	Sample request JSON
Example Response:	—	Sample response JSON
Example:	Examples:	Generic example (used as request)
Notes:	Note:	Additional context

Args: Format

Each argument follows this pattern (indent with 2–4 spaces):

    arg_name (type): Description of the argument.
        Continuation lines are joined automatically.
    another_arg (str, optional): This one is optional.

> Note: If you use Python type hints in the signature, you can skip the (type) part in the docstring — frappe_doc will automatically read them from the signature. Only add the type in the docstring when you need to be more descriptive (e.g., (str, optional), (list of dict)).

Example Request: and Example Response:

Use fenced JSON code blocks for the best rendering:

    Example Request:
        {
            "employee": "EMP-001",
            "leave_type": "Casual Leave"
        }

    Example Response:
        {
            "status": "success",
            "application": "HR-LAP-2024-00001"
        }

Or inline JSON (frappe_doc will auto-detect and pretty-print it):

    Example Request:
        {"employee": "EMP-001", "leave_type": "Casual Leave"}

---

Full Example — Best Practice API

Here is the ideal frappe_doc-optimized API function:

@frappe.whitelist(methods=["POST"])
def apply_for_leave(
    employee: str,
    leave_type: str,
    from_date: str,
    to_date: str,
    reason: str = "",
    half_day: bool = False,
    half_day_date: str | None = None,
) -> dict:
    """Submit a new Leave Application for an employee.

    Creates a Leave Application document, validates leave balance,
    and notifies the employee's leave approver via email.

    Args:
        employee (str): The Employee ID (e.g., "EMP-0001").
        leave_type (str): Name of the Leave Type (e.g., "Casual Leave").
        from_date (str): Leave start date in YYYY-MM-DD format.
        to_date (str): Leave end date in YYYY-MM-DD format.
        reason (str, optional): Reason for the leave. Defaults to empty string.
        half_day (bool, optional): Whether to apply for a half day. Defaults to False.
        half_day_date (str, optional): Date of the half day, required when half_day is True.

    Returns:
        dict: A result object with ``status`` ("success" or "error"),
              ``name`` (the created document name), and ``message``.

    Raises:
        frappe.ValidationError: If leave balance is insufficient or dates are invalid.
        frappe.PermissionError: If the user is not authorized to apply leave for this employee.

    Example Request:
        {
            "employee": "EMP-0001",
            "leave_type": "Casual Leave",
            "from_date": "2024-08-01",
            "to_date": "2024-08-03",
            "reason": "Family function"
        }

    Example Response:
        {
            "status": "success",
            "name": "HR-LAP-2024-00042",
            "message": "Leave Application submitted successfully."
        }
    """
    # ... implementation ...

What frappe_doc renders for this function:

• ✅ Method badge: POST (explicit, solid badge)
• ✅ Parameter pills: employee: str · leave_type: str · from_date: str · to_date: str · reason: str · half_day: bool · half_day_date: str | None
• ✅ Summary: "Submit a new Leav