📚 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

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:

Tip: Use explicit method declarations to override inference and get the most accurate documentation:

@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:

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 <api_key>:<api_secret>" \

  -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)

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:

        ```

{% endraw %}

json

        {

            "employee": "EMP-001",

            "leave_type": "Casual Leave"

        }

{% raw %}



        ```



    Example Response:

        ```

{% endraw %}

json

        {

            "status": "success",

            "application": "HR-LAP-2024-00001"

        }

{% raw %}



        ```

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:

        ```



json

        {

            "employee": "EMP-0001",

            "leave_type": "Casual Leave",

            "from_date": "2024-08-01",

            "to_date": "2024-08-03",

            "reason": "Family function"

        }





        ```



    Example Response:

        ```



json

        {

            "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 Leave Application for an employee."


• ✅ Description paragraph about what the function does


• ✅ Full parameter table with types and descriptions


• ✅ Returns documentation


• ✅ Side-by-side JSON example panels


• ✅ Try It Out form pre-filled with example values

Docstring Section Reference

json block |

| JSON response example | `Example Response:` + fenced



json block |

| Generic example | Example: or Examples: + fenced



```json block |

DocType Field Explorer

Switch to the DocType Fields tab to browse the schema of any DocType installed on your site.

Hierarchical Child Tables

This is the feature that will change how you develop on Frappe forever.

In standard Frappe development, if a DocType has a child table field (e.g., Sales Order → Items), you have to:

1. Open the DocType list


2. Search for "Sales Order"


3. Find the items field


4. Note that it links to Sales Order Item
   


5. Open a new browser tab for the DocType list


6. Search for "Sales Order Item"


7. Browse its fields

With frappe_doc, this is one click.

The DocType Field Explorer renders child table fields as collapsible, indented trees. Click the arrow next to any Table or Table MultiSelect field to expand it and see all child table fields inline — no navigation required.

plaintext

▾ Sales Order

  ├── customer           Link → Customer

  ├── delivery_date      Date

  ├── po_no              Data

  ▾ items                Table → Sales Order Item      [EXPAND]

    │  ├── item_code      Link → Item                  required

    │  ├── item_name      Data

    │  ├── qty            Float                        required

    │  ├── rate           Currency

    │  ├── amount         Currency                     in_list_view

    │  └── warehouse      Link → Warehouse

  ▾ taxes                Table → Sales Taxes and Charges

    │  ├── charge_type    Select

    │  └── tax_amount     Currency

This gives you the complete picture of a document's data structure in one place.

Field Search

Use the search bar in the DocType Fields tab to filter fields by:

Each field row shows:

• 
  Fieldname (monospaced, bold for top-level fields)


• 
  Label (greyed out, human-readable)


• 
  Type badge (with the linked DocType for Link / Table fields)


• 
  reqd badge for required fields


• 
  in_list_view badge for fields visible in list view

FAQ

Q: Does frappe_doc import or execute any of my app's code during scanning?


A: No. frappe_doc uses Python's ast module to parse source files as text. Your code is never imported or executed during the scan. This makes it completely safe to use even on production servers.

Q: How often does it re-scan?


A: Scan results are cached in Redis for 1 hour. Click the Refresh Cache button at any time to force an immediate re-scan.

Q: Does it work with async functions?


A: Yes. Both def and async def functions decorated with @frappe.whitelist() are discovered and documented.

Q: Do I need to restart the server after installing?


A: No. Just run bench --site mysite clear-cache and navigate to /app/developer_portal.

Q: My new API isn't showing up. What do I do?


A: Click the Refresh Cache button in the API Explorer. The 1-hour cache is serving the old scan result.

Q: Does it work with custom apps?


A: Yes. frappe_doc scans every installed app on your site — including all your custom apps. There is nothing to configure.

Q: What if I don't write any docstrings?


A: frappe_doc still documents your API. It shows the route, parameter names (from the function signature), type hints (if you use them), and inferred HTTP method. But you'll get much richer documentation if you add docstrings.

Q: Can I document APIs that already use Google-style docstrings from another style guide?


A: Yes. frappe_doc recognizes all the standard Google-style section headers (Args:, Returns:, Example:, etc.) and is designed to work with existing codebases without any changes.

Summary

Stop treating your Frappe backend like a black box.

frappe_doc gives every developer on your team — whether they're building JavaScript frontends, writing Python integrations, or onboarding as a new hire — a single, searchable, interactive portal to understand and test every API in your entire Frappe ecosystem.

All it takes is writing clean Python code the way you already should be. Add type hints. Add a docstring. frappe_doc does the rest.

Then open /doc in your browser. That's it. 🚀

frappe_doc is open source and built with ❤️ for the Frappe community.