### Generate Documentation via CLI

Source: https://context7.com/markvincze/sabledocs/llms.txt

Install the package, generate a descriptor file using protoc, and run the generator.

```bash
# Install sabledocs
pip install sabledocs

# Generate descriptor from proto files (requires protoc)
protoc *.proto -o descriptor.pb --include_source_info

# Generate documentation with default settings
sabledocs

# Output is created in sabledocs_output/ directory
# Open sabledocs_output/index.html to view documentation
```

--------------------------------

### Create landing page introduction

Source: https://context7.com/markvincze/sabledocs/llms.txt

Example markdown content for the documentation landing page.

```markdown
<!-- intro.md -->
# Welcome to the Payment API

This documentation covers the gRPC services and Protobuf messages for our payment processing platform.

## Quick Start

```protobuf
// Example: Create a payment request
message CreatePaymentRequest {
  string customer_id = 1;
  int64 amount_cents = 2;
  string currency = 3;
}
```
```

--------------------------------

### Build and Run Sabledocs (Bash)

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Sequence of commands to build CSS, install Sabledocs, generate documentation, and open the index file using Bash.

```bash
npm run css-build && pip install .. && sabledocs && .\output\index.html
```

--------------------------------

### Install Package from Local Folder

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Command to install the Python package in editable mode from the local directory.

```bash
pip install -e .
```

--------------------------------

### Build and Run Sabledocs (PowerShell)

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Sequence of commands to build CSS, install Sabledocs, generate documentation, and open the index file using PowerShell.

```powershell
npm run css-build; pip install ..; sabledocs; .\output\index.html
```

--------------------------------

### Invoke gRPC Service via grpcurl

Source: https://context7.com/markvincze/sabledocs/llms.txt

Example command to test a gRPC service method using grpcurl.

```bash
grpcurl -d '{"customer_id": "cust_123", "amount": 1000}' \
  api.example.com:443 payment.v1.PaymentService/CreatePayment
```

--------------------------------

### Sabledocs Configuration Options

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Customize Sabledocs behavior by creating a sabledocs.toml file. This example shows various configuration options for titles, input/output files, search, footer, repository links, comment handling, hidden packages, and member ordering.

```toml
# Configures the main title of the documentation site.
# Default value: "Protobuf module documentation"
module-title = "My Awesome Module"

# Specifies the name of the Protobuf descriptor file.
# Default value: "descriptor.pb"
input-descriptor-file = "myawesomemodule.pb"

# Specifies the file which contains the content to display on the main page above the package list.
# Default value: ""
main-page-content-file = "intro.md"

# The output folder to which the documentation is generated.
# Default value: "sabledocs_output"
output-dir = "docs"

# Controls whether the the search functionality is enabled with a prebuilt Lunr index.
# Default value: true
enable-lunr-search = true

# Copyright message displayed in the footer.
# Default value: ""
footer-content = "© 2023 Jane Doe. All rights reserved."

# The following 3 fields configure the source control repository of the project.
# They are used to generate deeplinks for the members of the Proto model pointing to the original source
# code. By default these fields are not configured, and source code links are not included in the docs.
# The repository-type field supports the following possible values, "github", "bitbucket", "bitbucket-data-center" and "gitlab".
# The fields repository-url and repository-branch should be configured to point to the correct repository.
# repository-dir should be set only if the root of your Protobuf module is in a specific directory inside your repository.
repository-type = "github"
repository-url = "https://github.com/janedoe/myawesomeproject"
repository-branch = "main"
repository-dir = "proto"

# In each comment, ignore everything that comes after (until end of the comment) one of the keywords.
# Default value: []
ignore-comments-after = ["@exclude"]
# In each comment, ignore all lines that contain at least one keyword from the following list.
# Default value: []
ignore-comment-lines-containing = ["buf:lint"]

# Packages can be hidden from the generated documentation by adding them to the hidden-packages
# collection. In the templates, the field non_hidden_packages can be used to access the packages which are
# not listed in hidden-packages. (And the packages field returns all packages.)
# Default value: []
hidden-packages = ["google.protobuf"]

# By default, packages and members in a package are ordered alphabetically.
# By setting the member-ordering option to "preserve", the original order present in the Protobuf
# definitions will be preserved.
# When using the "preserve" option and having multiple proto input files, the order of the members will
# depend not just on the physical order in the Protobuf files, but also on the order in which the files
# were listed in the input when `protoc` was executed.
# Default value: ""
member-ordering = "preserve"

```

--------------------------------

### Create custom HTML template

Source: https://context7.com/markvincze/sabledocs/llms.txt

An example HTML template using Jinja2 syntax to display service and enum information.

```html
<!-- extra-templates/api-overview.html -->
<!DOCTYPE html>
<html>
<head>
    <title>API Overview - {{ sable_config.module_title }}</title>
</head>
<body>
    <h1>API Overview</h1>
    <h2>All Services ({{ all_messages | length }} messages)</h2>
    <ul>
        {% for package in non_hidden_packages %}
        <li>
            <strong>{{ package.name }}</strong>
            <ul>
                {% for service in package.services %}
                <li>{{ service.full_name }} ({{ service.methods | length }} methods)</li>
                {% endfor %}
            </ul>
        </li>
        {% endfor %}
    </ul>

    <h2>All Enums</h2>
    <ul>
        {% for enum in all_enums %}
        <li>{{ enum.full_name }}</li>
        {% endfor %}
    </ul>
</body>
</html>
```

--------------------------------

### Install Sabledocs Package

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Install the sabledocs Python package using pip. Python version 3.11 or higher is required.

```bash
pip install sabledocs
```

--------------------------------

### Define Protobuf Message with Comments

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Example of a Protobuf message definition with comments, including a markdown-formatted code block within a single-line comment.

```protobuf
// These are the comments for SearchRequest
//
// ```
// namespace Test
// {
//     public class Foo {
//         public string Bar { get; set; }
//     }
// }
// ```
message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 results_per_page = 3;
}
```

--------------------------------

### Specify Main Page Content File

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Configure the file that contains custom introduction content for the main documentation page.

```toml
main-page-content-file = "intro.md"
```

--------------------------------

### Run Sabledocs to Build Documentation

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Execute the sabledocs command in the folder containing the descriptor.pb file to generate documentation. The output will be in the 'sabledocs_output' folder.

```bash
sabledocs
```

--------------------------------

### Define gRPC Service in Proto

Source: https://context7.com/markvincze/sabledocs/llms.txt

A sample proto file structure demonstrating service and message definitions with documentation comments.

```protobuf
// payment.proto
syntax = "proto3";

package payment.v1;

// PaymentService handles all payment-related operations.
//
// This service provides methods for creating, retrieving, and managing payments.
// All monetary amounts are represented in the smallest currency unit (e.g., cents).
//
// ```
// Example usage:
// grpcurl -d '{"customer_id": "cust_123", "amount": 1000}' \
//   api.example.com:443 payment.v1.PaymentService/CreatePayment
// ```
service PaymentService {
  // CreatePayment initiates a new payment transaction.
  //
  // Returns the created payment with a unique identifier.
  // The payment starts in PENDING status.
  rpc CreatePayment(CreatePaymentRequest) returns (Payment);

  // GetPayment retrieves a payment by its unique identifier.
  rpc GetPayment(GetPaymentRequest) returns (Payment);

  // ListPayments returns all payments for a customer.
  rpc ListPayments(ListPaymentsRequest) returns (ListPaymentsResponse);
}

// Payment represents a single payment transaction.
message Payment {
  // Unique identifier for the payment (format: pay_xxxxx)
  string id = 1;

  // Customer who initiated the payment
  string customer_id = 2;

  // Payment amount in smallest currency unit (e.g., cents)
  int64 amount = 3;

  // ISO 4217 currency code (e.g., "USD", "EUR")
  string currency = 4;

  // Current status of the payment
  PaymentStatus status = 5;

  // Timestamp when payment was created (RFC 3339)
  string created_at = 6;
}

// CreatePaymentRequest contains the data needed to create a new payment.
message CreatePaymentRequest {
  // Customer identifier (required)
  string customer_id = 1;

  // Amount in smallest currency unit (required, must be positive)
  int64 amount = 2;

  // ISO 4217 currency code (default: "USD")
  string currency = 3;

  // Optional idempotency key to prevent duplicate payments
  optional string idempotency_key = 4;
}

// PaymentStatus represents the lifecycle state of a payment.
enum PaymentStatus {
  // Default unspecified status
  PAYMENT_STATUS_UNSPECIFIED = 0;

  // Payment is being processed
  PAYMENT_STATUS_PENDING = 1;

  // Payment completed successfully
  PAYMENT_STATUS_COMPLETED = 2;

  // Payment failed (see failure_reason for details)
  PAYMENT_STATUS_FAILED = 3;

  // Payment was refunded
  PAYMENT_STATUS_REFUNDED = 4;
}
```

--------------------------------

### Automate Documentation Generation Workflow

Source: https://context7.com/markvincze/sabledocs/llms.txt

A shell script demonstrating the full process of compiling proto files and generating documentation with Sabledocs.

```bash
#!/bin/bash
# generate_docs.sh - Complete documentation workflow

# Step 1: Compile proto files to descriptor
echo "Compiling proto files..."
protoc \
  --proto_path=./proto \
  --include_source_info \
  --include_imports \
  -o ./descriptor.pb \
  ./proto/**/*.proto

# Step 2: Create configuration file
cat > sabledocs.toml << 'EOF'
module-title = "Payment Platform API"
input-descriptor-file = "descriptor.pb"
output-dir = "docs"
enable-lunr-search = true
main-page-content-file = "intro.md"
footer-content = "© 2024 Payment Platform Inc."
repository-type = "github"
repository-url = "https://github.com/mycompany/payment-api"
repository-branch = "main"
repository-dir = "proto"
hidden-packages = ["google.protobuf", "google.api"]
member-ordering = "preserve"
EOF

# Step 3: Create intro page
cat > intro.md << 'EOF'
# Payment Platform API

Welcome to the Payment Platform API documentation.

## Overview
This API provides gRPC services for payment processing, refunds, and reporting.
EOF

# Step 4: Generate documentation
echo "Generating documentation..."
sabledocs

# Step 5: Serve locally for preview (optional)
echo "Documentation available at docs/index.html"
python -m http.server 8000 --directory docs
```

--------------------------------

### Include static content

Source: https://context7.com/markvincze/sabledocs/llms.txt

Demonstrates the directory structure for static files and how to reference them in markdown.

```bash
# Directory structure
project/
├── sabledocs.toml
├── descriptor.pb
├── intro.md
└── static/              # All files copied to output root
    ├── logo.png
    ├── custom.css
    └── diagrams/
        └── architecture.svg
```

```markdown
<!-- intro.md - Reference static files in markdown -->
# My API Documentation

![Company Logo](logo.png)

## Architecture Overview

![Architecture Diagram](diagrams/architecture.svg)

See our [style guide](custom.css) for theming information.
```

--------------------------------

### Configure Sabledocs with TOML

Source: https://context7.com/markvincze/sabledocs/llms.txt

Define input/output paths, repository metadata, and filtering rules in sabledocs.toml.

```toml
# sabledocs.toml - Full configuration example

# Main title displayed on the documentation site
module-title = "My API Documentation"

# Input Protobuf descriptor file (generated by protoc)
input-descriptor-file = "descriptor.pb"

# Output directory for generated documentation
output-dir = "docs"

# Enable/disable search functionality with Lunr
enable-lunr-search = true

# Markdown file for main page introduction content
main-page-content-file = "intro.md"

# Footer copyright message
footer-content = "© 2024 My Company. All rights reserved."

# Repository configuration for source code deep links
repository-type = "github"  # Options: github, gitlab, bitbucket, bitbucket-data-center
repository-url = "https://github.com/myorg/myrepo"
repository-branch = "main"
repository-dir = "proto"  # Subdirectory containing proto files

# Comment filtering - ignore content after these keywords
ignore-comments-after = ["@exclude", "@internal"]

# Remove lines containing these keywords from comments
ignore-comment-lines-containing = ["buf:lint", "TODO"]

# Hide specific packages from documentation
hidden-packages = ["google.protobuf", "internal.v1"]

# Ordering: "" for alphabetical, "preserve" for original order
member-ordering = "preserve"

# Markdown extensions for comment rendering
markdown-extensions = ["fenced_code", "nl2br", "tables"]
```

--------------------------------

### Run sabledocs with Docker

Source: https://context7.com/markvincze/sabledocs/llms.txt

Commands for running sabledocs via Docker or docker-compose for CI/CD pipelines.

```bash
# Pull the Docker image
docker pull markvincze/sabledocs

# Generate documentation from proto files
docker run -v $(pwd):/workspace -w /workspace markvincze/sabledocs sh -c \
  "protoc *.proto -o descriptor.pb --include_source_info && sabledocs"
```

```yaml
# docker-compose.yml
version: '3'
services:
  docs:
    image: markvincze/sabledocs
    volumes:
      - ./proto:/workspace
      - ./docs-output:/workspace/sabledocs_output
    working_dir: /workspace
    command: >
      sh -c "protoc *.proto -o descriptor.pb --include_source_info && sabledocs"
```

--------------------------------

### Implement Client-Side Search with Lunr.js

Source: https://github.com/markvincze/sabledocs/blob/main/src/sabledocs/templates/_default/search.html

This script initializes a Lunr index and renders search results based on URL query parameters. It requires the search_documents and search_index variables to be injected into the template.

```javascript
const searchDocuments = {{ search_documents | safe }}; const searchIndex = {{ search_index | safe }}; const idx = lunr.Index.load(searchIndex); function displaySearchResults() { const query = new URLSearchParams(window.location.search).get('query'); if (query) { document.getElementById('mainInputQuery').value = query; const results = idx.query(function (q) { words = query.toLowerCase().split(" "); // toLowerCase() is needed to make the search case insensitive. for (n in words) { const word = words[n]; if (!word) { continue; } // look for an exact match and apply a large positive boost q.term(word, { usePipeline: true, boost: 100 }) // look for terms that match the beginning of this queryTerm and apply a medium boost q.term(word + "*", { usePipeline: false, boost: 10 }) } }); const searchResults = document.getElementById('searchResults'); if (results.length > 0) { let resultList = '' for (const n in results) { // Use the unique ref from the results list to get the full item // so you can build its <li> const doc = searchDocuments[results[n].ref] resultList += '<h5 class="title is-5 mt-3"><a href="' + doc.url + '">' + doc.package + '</a></h5>' // Add a short clip of the content resultList += '<p>' + doc.content.substring(0, 150) + '...</p><hr />' } searchResults.innerHTML = resultList } else { searchResults.innerHTML = '<p>No search results.</p>'; } } } window.addEventListener("load", displaySearchResults);
```

--------------------------------

### Generate Proto Descriptor with Protoc

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Use the protoc compiler to generate a binary descriptor from your Proto contracts. Ensure the --include_source_info flag is used to include comments in the documentation.

```bash
protoc *.proto -o descriptor.pb --include_source_info
```

--------------------------------

### Configure sabledocs.toml for extra templates

Source: https://context7.com/markvincze/sabledocs/llms.txt

Defines the directory and file suffix for custom HTML templates.

```toml
extra-template-path = "extra-templates"
extra-template-suffix = ".html"  # Only process files with this suffix
```

--------------------------------

### Configure Extra Jinja Templates and Suffix

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Define paths for extra Jinja templates and their file suffix. Subdirectories prefixed with '_' are ignored.

```toml
extra-template-path = "extra-templates"
extra-template-suffix = ".tpl" # default value is ".html"
```

--------------------------------

### Build Python Package

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Command to build the Python package using the 'build' module.

```bash
python -m build
```

--------------------------------

### Publish Package to TestPyPI

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Command to upload the built Python package to the TestPyPI repository using 'twine'.

```bash
python -m twine upload --repository testpypi dist/*
```

--------------------------------

### Service Documentation

Source: https://github.com/markvincze/sabledocs/blob/main/src/sabledocs/templates/_default/service.html

Details about the available services and their methods.

```APIDOC
## Service Documentation

This section provides details about the available services and their associated RPC methods.

### Service: `{{ service.name }}`

**Description:** {{ service.description_html | safe }}

{% for method in service.methods %}

##### RPC Method: `{{ method.name }}`

**Request Type:** `{{ common.type_name(method.request) | trim }}`
**Response Type:** `{{ common.type_name(method.response) }}`

{% if method.description_html %}

**Description:** {{ method.description_html | safe }}

{% endif %}

{% endfor %}
```

--------------------------------

### Configure Markdown Extensions

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Specify markdown extensions to be used by Sabledocs. 'fenced_code' and 'nl2br' are common choices.

```toml
markdown-extensions = ["fenced_code", "nl2br"]
```

--------------------------------

### Set Custom Jinja Template Path

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Specify a directory for custom Jinja templates to override Sabledocs' default templates.

```toml
template-path = "templates"
```

--------------------------------

### Enum Documentation

Source: https://github.com/markvincze/sabledocs/blob/main/src/sabledocs/templates/_default/enum.html

This section details the structure and values of enums within SableDocs.

```APIDOC
## Enum Documentation

### Description
This section details the structure and values of enums within SableDocs.

### Enum Structure

#### `{{ enum.name }}`

**Description:** {{ enum.description_html | safe }}

{% if enum.repository_url %} **Source:** [{{ enum.source_file_path }}]({{ enum.repository_url }}) {% endif %}

### Enum Values

| Name | Number | Description |
|---|---|---|
{% for enum_value in enum.values %}
| `{{ enum_value.name }}` | {{ enum_value.number }} | {{ enum_value.description_html | safe }} |
{% endfor %}
```

--------------------------------

### Implement custom comment parser

Source: https://context7.com/markvincze/sabledocs/llms.txt

Configures a custom Python parser for processing JSON-formatted comments in Protobuf files.

```toml
# sabledocs.toml
comments-parser-file = "custom_parser.py"
```

```python
# custom_parser.py - Custom comment parser for JSON-formatted comments
import json
import re

class CustomCommentsParser(CommentsParser):
    """Parse JSON-structured comments and extract documentation fields."""

    def __init__(self):
        pass

    def ParseAll(self, comment):
        """Process all comment types - extracts 'desc' field from JSON comments."""
        # Normalize whitespace for JSON parsing
        comment_simple = ' '.join(comment.split())

        try:
            comments_dict = json.loads(comment_simple)
            if "desc" in comments_dict:
                # Convert <p> tags to markdown paragraphs
                comment = re.sub(r'<p>', r'\n\n', comments_dict["desc"])

                # Optionally handle other fields
                if "deprecated" in comments_dict:
                    comment = f"**DEPRECATED**: {comments_dict['deprecated']}\n\n{comment}"
                if "since" in comments_dict:
                    comment = f"{comment}\n\n*Since version {comments_dict['since']}*"
        except json.decoder.JSONDecodeError:
            # Return original comment if not valid JSON
            pass

        return comment

    def ParseMessage(self, comment):
        """Custom processing for message comments."""
        return self.ParseAll(comment)

    def ParseField(self, comment):
        """Custom processing for field comments."""
        return self.ParseAll(comment)

    def ParseService(self, comment):
        """Custom processing for service comments."""
        return self.ParseAll(comment)

    def ParseServiceMethod(self, comment):
        """Custom processing for service method comments."""
        return self.ParseAll(comment)

    def ParseEnum(self, comment):
        """Custom processing for enum comments."""
        return self.ParseAll(comment)

    def ParseEnumValue(self, comment):
        """Custom processing for enum value comments."""
        return self.ParseAll(comment)
```

--------------------------------

### Customize Templates

Source: https://context7.com/markvincze/sabledocs/llms.txt

Override default Jinja2 templates by specifying a template path in the configuration.

```toml
# sabledocs.toml
template-path = "my-templates"
```

```html
<!-- my-templates/package.html - Custom package template -->
<!DOCTYPE html>
<html>
<head>
    <title>{{ package.name }} - {{ sable_config.module_title }}</title>
    <link rel="stylesheet" href="static/mystyles.css">
</head>
<body>
    <h1>{{ package.name }}</h1>
    <div class="description">{{ package.description_html | safe }}</div>

    <!-- Services -->
    {% for service in package.services %}
    <section class="service">
        <h2>{{ service.name }}</h2>
        <p>{{ service.description_html | safe }}</p>
        {% for method in service.methods %}
        <div class="method">
            <code>{{ method.name }}({{ method.request.type }}) returns {{ method.response.type }}</code>
            <p>{{ method.description_html | safe }}</p>
        </div>
        {% endfor %}
    </section>
    {% endfor %}

    <!-- Messages -->
    {% for message in package.messages %}
    <section class="message">
        <h2>{{ message.name }}</h2>
        <p>{{ message.description_html | safe }}</p>
        <table>
            <tr><th>Field</th><th>Type</th><th>Description</th></tr>
            {% for field in message.fields %}
            <tr>
                <td>{{ field.name }}</td>
                <td>{{ field.label }} {{ field.type }}</td>
                <td>{{ field.description_html | safe }}</td>
            </tr>
            {% endfor %}
        </table>
    </section>
    {% endfor %}

    <!-- Enums -->
    {% for enum in package.enums %}
    <section class="enum">
        <h2>{{ enum.name }}</h2>
        <ul>
            {% for value in enum.values %}
            <li><code>{{ value.name }} = {{ value.number }}</code> - {{ value.description_html | safe }}</li>
            {% endfor %}
        </ul>
    </section>
    {% endfor %}
</body>
</html>
```

--------------------------------

### Format Type Name with Package Linking

Source: https://github.com/markvincze/sabledocs/blob/main/src/sabledocs/templates/_default/type_name.html

Use this macro to format a message field's type name. It trims whitespace and conditionally adds a link to the package if the type is a MESSAGE and the package is visible.

```jinja
{%- macro type_name(message_field) -%}
  {%- if message_field.package and not message_field.is_package_hidden and message_field.type_kind != "UNKNOWN" -%}
    {%- if message_field.type_kind == "MESSAGE" -%}
      [{%- else -%}]
    ({{ message_field.package.name if message_field.package.name else ) 
    [{%- endif -%}
      {{ message_field.full_type }}
    ]({{ message_field.package.name if message_field.package.name else )
  {%- else -%}
    {{ message_field.full_type }}
  {%- endif -%}
{%- endmacro -%}

```

--------------------------------

### RefundService API

Source: https://context7.com/markvincze/sabledocs/llms.txt

Details for the RefundService, which handles refunds and chargebacks.

```APIDOC
## RefundService API

### Description
Handles refunds and chargebacks for payment transactions.

### Authentication
All API calls require a valid API key passed in the `x-api-key` metadata header.

*(Note: Specific RPC methods for RefundService are not detailed in the provided text. Please refer to the proto file or other documentation for specific endpoints.)*
```

--------------------------------

### Specify Custom Comments Parser

Source: https://github.com/markvincze/sabledocs/blob/main/README.md

Indicate a Python script that defines a class inheriting from CommentsParser for pre-processing comment strings.

```toml
comments-parser-file = "sample/custom_comments_parser.py"
```

--------------------------------

### Message Structure

Source: https://github.com/markvincze/sabledocs/blob/main/src/sabledocs/templates/_default/message.html

Defines the structure of a message, including its fields, nested messages, and source information.

```APIDOC
## Message {{ message.name }}

### Description
{{ message.description_html | safe }}

{% if message.repository_url %}
### Source
[{{ message.source_file_path }}]({{ message.repository_url }})
{% endif %}

### Fields

| Field | Type | Description | Default Value |
|---|---|---|---|
{% for field in message.non_oneof_fields %}
| {{ field.number }} | `{% if field.label != "" %} {{ field.label }} {% endif %} {{ common.type_name(field) }}` | {{ field.description_html | safe }} | {{ field.default_value }} |
{% endfor %}

{% for oneof_field_group in message.oneof_field_groups %}
#### oneof {{ oneof_field_group.name }}

| Field | Type | Description | Default Value |
|---|---|---|---|
{% for field in oneof_field_group.fields %}
| {{ field.number }} | `{% if field.label != "" %} {{ field.label }} {% endif %} {{ common.type_name(field) }}` | {{ field.description_html | safe }} | {{ field.default_value }} |
{% endfor %}
{% endfor %}
```

--------------------------------

### PaymentService API

Source: https://context7.com/markvincze/sabledocs/llms.txt

Details for the PaymentService, including its RPC methods and associated messages.

```APIDOC
## PaymentService API

### Description
Handles all payment-related operations, including creating, retrieving, and managing payments. All monetary amounts are represented in the smallest currency unit (e.g., cents).

### Authentication
All API calls require a valid API key passed in the `x-api-key` metadata header.

### RPC Methods

#### CreatePayment

##### Description
Initiates a new payment transaction. Returns the created payment with a unique identifier. The payment starts in PENDING status.

##### Method
`POST` (gRPC equivalent)

##### Endpoint
`/payment.v1.PaymentService/CreatePayment`

##### Parameters

###### Request Body
- **customer_id** (string) - Required - Customer identifier
- **amount** (int64) - Required - Amount in smallest currency unit (must be positive)
- **currency** (string) - Optional - ISO 4217 currency code (default: "USD")
- **idempotency_key** (string) - Optional - Idempotency key to prevent duplicate payments

##### Request Example
```json
{
  "customer_id": "cust_123",
  "amount": 1000,
  "currency": "USD",
  "idempotency_key": "unique-key-123"
}
```

##### Response

###### Success Response (200)
- **id** (string) - Unique identifier for the payment (format: pay_xxxxx)
- **customer_id** (string) - Customer who initiated the payment
- **amount** (int64) - Payment amount in smallest currency unit (e.g., cents)
- **currency** (string) - ISO 4217 currency code (e.g., "USD", "EUR")
- **status** (PaymentStatus) - Current status of the payment
- **created_at** (string) - Timestamp when payment was created (RFC 3339)

###### Response Example
```json
{
  "id": "pay_abcde",
  "customer_id": "cust_123",
  "amount": 1000,
  "currency": "USD",
  "status": "PAYMENT_STATUS_PENDING",
  "created_at": "2023-10-27T10:00:00Z"
}
```

#### GetPayment

##### Description
Retrieves a payment by its unique identifier.

##### Method
`GET` (gRPC equivalent)

##### Endpoint
`/payment.v1.PaymentService/GetPayment`

##### Parameters

###### Query Parameters
- **id** (string) - Required - Unique identifier for the payment

##### Response

###### Success Response (200)
- **id** (string) - Unique identifier for the payment (format: pay_xxxxx)
- **customer_id** (string) - Customer who initiated the payment
- **amount** (int64) - Payment amount in smallest currency unit (e.g., cents)
- **currency** (string) - ISO 4217 currency code (e.g., "USD", "EUR")
- **status** (PaymentStatus) - Current status of the payment
- **created_at** (string) - Timestamp when payment was created (RFC 3339)

#### ListPayments

##### Description
Returns all payments for a customer.

##### Method
`GET` (gRPC equivalent)

##### Endpoint
`/payment.v1.PaymentService/ListPayments`

##### Parameters

###### Query Parameters
- **customer_id** (string) - Required - The ID of the customer whose payments to list.

##### Response

###### Success Response (200)
- **payments** (array) - A list of payments for the customer.

###### Response Example
```json
{
  "payments": [
    {
      "id": "pay_abcde",
      "customer_id": "cust_123",
      "amount": 1000,
      "currency": "USD",
      "status": "PAYMENT_STATUS_COMPLETED",
      "created_at": "2023-10-27T10:00:00Z"
    },
    {
      "id": "pay_fghij",
      "customer_id": "cust_123",
      "amount": 500,
      "currency": "USD",
      "status": "PAYMENT_STATUS_PENDING",
      "created_at": "2023-10-27T11:00:00Z"
    }
  ]
}
```

### Data Types

#### Payment

##### Description
Represents a single payment transaction.

##### Fields
- **id** (string) - Unique identifier for the payment (format: pay_xxxxx)
- **customer_id** (string) - Customer who initiated the payment
- **amount** (int64) - Payment amount in smallest currency unit (e.g., cents)
- **currency** (string) - ISO 4217 currency code (e.g., "USD", "EUR")
- **status** (PaymentStatus) - Current status of the payment
- **created_at** (string) - Timestamp when payment was created (RFC 3339)

#### PaymentStatus (Enum)

##### Description
Represents the lifecycle state of a payment.

##### Values
- **PAYMENT_STATUS_UNSPECIFIED**: Default unspecified status
- **PAYMENT_STATUS_PENDING**: Payment is being processed
- **PAYMENT_STATUS_COMPLETED**: Payment completed successfully
- **PAYMENT_STATUS_FAILED**: Payment failed (see failure_reason for details)
- **PAYMENT_STATUS_REFUNDED**: Payment was refunded

```

--------------------------------

### ReportingService API

Source: https://context7.com/markvincze/sabledocs/llms.txt

Details for the ReportingService, which provides transaction reporting and analytics.

```APIDOC
## ReportingService API

### Description
Provides transaction reporting and analytics.

### Authentication
All API calls require a valid API key passed in the `x-api-key` metadata header.

*(Note: Specific RPC methods for ReportingService are not detailed in the provided text. Please refer to the proto file or other documentation for specific endpoints.)*
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.