### Install scalar_doc Package

Source: https://github.com/iagobalmeida/scalar_doc/blob/main/README.md

Use pip to install the scalar_doc package. This is the primary step to begin using the library.

```bash
pip install scalar_doc
```

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

### CLI Configuration via TOML

Source: https://github.com/iagobalmeida/scalar_doc/blob/main/README.md

Customize ScalarDoc theme and settings by creating a pyproject.toml or scalar_doc.toml file. The CLI automatically loads these settings. This example shows basic theme and configuration options.

```toml
[tool.scalar_doc]
favicon_url = "https://example.com/favicon.ico"

[tool.scalar_doc.theme.light]
color_1 = "#191414"
background_1 = "#ffffff"

[tool.scalar_doc.theme.dark]
color_1 = "#ffffff"
background_1 = "#191414"

[tool.scalar_doc.config]
hide_sidebar = true
show_models = false

```

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

### Configure Scalar UI Behavior

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Use ScalarConfiguration to control UI elements like sidebar, search, and examples. Apply the configuration to a ScalarDoc instance before rendering.

```python
from scalar_doc import ScalarDoc, ScalarConfiguration

config = ScalarConfiguration(
    show_sidebar=True,           # Show the left sidebar (default: True)
    enable_search=True,          # Enable search bar (default: True)
    hide_download_button=True,   # Hide spec download button
    hide_internal=True,          # Hide endpoints tagged as internal
    show_webhooks=False,         # Hide webhook definitions
    show_examples=True,          # Show request/response examples
    expand_table_of_contents=True,  # Expand TOC by default
    auth_persist=True,           # Persist auth tokens across sessions
    with_default_fonts=True,     # Use Scalar's default fonts
)

docs = ScalarDoc.from_spec("https://petstore3.swagger.io/api/v3/openapi.json", mode="url")
docs.set_configuration(config)
docs.to_file("docs.html")
# => docs.html rendered with the specified UI behavior
```

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

### CLI Usage with Local OpenAPI File

Source: https://github.com/iagobalmeida/scalar_doc/blob/main/README.md

Generate documentation from a local OpenAPI JSON file using the command-line interface. Specify the input file and the output HTML file.

```bash
scalar_doc path/to/openapi.json --mode json --output docs.html
```

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

### Configure Theme and Settings with scalar_doc.toml

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Define theme colors, favicon, logo, and UI settings in a `scalar_doc.toml` file. The CLI automatically loads this configuration when present in the current working directory.

```bash
cat > scalar_doc.toml << 'EOF'
[scalar_doc.theme]
favicon_url = "https://example.com/favicon.ico"

[scalar_doc.theme.light]
color_accent = "#0969da"
background_1 = "#ffffff"

[scalar_doc.theme.dark]
color_accent = "#58a6ff"
background_1 = "#0d1117"

[scalar_doc.config]
show_sidebar = true
hide_download_button = true
expand_table_of_contents = true
EOF
```

```bash
scalar_doc openapi.json --mode json --output docs.html
```

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

### Preview Resolved Configuration with Dry Run

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Use the `--dry-run` flag to preview the resolved configuration without generating an output file. The configuration is printed to standard output.

```bash
scalar_doc path/to/openapi.json --mode json --dry-run
```

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

### Configure Theme and Settings with pyproject.toml

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Customize theme and UI settings within a `pyproject.toml` file under the `[tool.scalar_doc]` section. The CLI automatically detects and loads these settings.

```toml
# pyproject.toml (use [tool.scalar_doc] section)
[tool.scalar_doc.theme]
favicon_url = "https://example.com/favicon.ico"
logo_url    = "https://example.com/logo-light.png"
logo_url_dark = "https://example.com/logo-dark.png"

[tool.scalar_doc.theme.light]
color_1    = "#191414"
color_accent = "#1DB954"
background_1 = "#ffffff"
background_2 = "#f0f0f0"
background_3 = "#e6e6e6"

[tool.scalar_doc.theme.dark]
color_1    = "#ffffff"
color_accent = "#1DB954"
background_1 = "#191414"
background_2 = "#121212"
background_3 = "#282828"

[tool.scalar_doc.config]
show_sidebar = true
hide_download_button = false
expand_table_of_contents = true
enable_search = true
```

```bash
# CLI will pick up the config automatically:
scalar_doc openapi.json --mode json --output docs.html
```

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

### Generate Spotify-style Documentation

Source: https://github.com/iagobalmeida/scalar_doc/blob/main/README.md

Loads the Spotify Web API specification and customizes the generated documentation with a title, header, configuration, and theme. This is useful for creating branded API documentation.

```python
from scalar_doc import (
    ScalarColorSchema,
    ScalarConfiguration,
    ScalarDoc,
    ScalarHeader,
    ScalarTheme,
)

spotify_docs = ScalarDoc.from_spec(
    "https://raw.githubusercontent.com/sonallux/spotify-web-api/refs/heads/main/official-spotify-open-api.yml"
)

spotify_docs.set_title("Spotify")
spotify_docs.set_header(
    ScalarHeader(
        logo_url="https://storage.googleapis.com/pr-newsroom-wp/1/2023/09/Spotify_Logo_RGB_Green.png",
        logo_url_dark="https://storage.googleapis.com/pr-newsroom-wp/1/2023/09/Spotify_Logo_RGB_White.png",
        links={"Spotify": "https://spotify.com"},
    )
)
spotify_docs.set_configuration(
    ScalarConfiguration(
        hide_download_button=True,
        show_models=False,
        expand_table_of_contents=True,
        schema_style="table",
    )
)
spotify_docs.set_theme(
    ScalarTheme(
        favicon_url="https://upload.wikimedia.org/wikipedia/commons/1/19/Spotify_logo_without_text.svg",
        color_scheme_light=ScalarColorSchema(
            color_1="#191414",
            color_2="#3e3e3e",
            color_3="#1DB954",
            background_1="#ffffff",
            background_2="#f0f0f0",
            background_3="#e6e6e6",
            color_accent="#1DB954",
            background_accent="#d2fbe3",
            link_color="#1DB954",
            code="#2b2b2b",
        ),
        color_scheme_dark=ScalarColorSchema(
            color_1="#ffffff",
            color_2="#aaaaaa",
            color_3="#1DB954",
            background_1="#191414",
            background_2="#121212",
            background_3="#282828",
            color_accent="#1DB954",
            background_accent="#1DB95433",
            link_color="#1DB954",
            code="#1DB954",
        ),
    )
)

```

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

### Programmatic Usage with Local OpenAPI File

Source: https://github.com/iagobalmeida/scalar_doc/blob/main/README.md

Generate documentation from a local OpenAPI JSON file. The specification is read from the file, and the documentation is exported to an HTML file.

```python
from scalar_doc import ScalarDocs

# From local JSON file
with open("openapi.json", "r", encoding="utf-8") as f:
    docs.set_spec(f.read(), mode="json")
    docs.to_file("docs/index_from_file.html")

```

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

### CLI Usage with Remote OpenAPI Spec

Source: https://github.com/iagobalmeida/scalar_doc/blob/main/README.md

Generate documentation from a remote OpenAPI specification URL using the command-line interface. Specify the URL and the output HTML file.

```bash
scalar_doc https://api.example.com/openapi.json --output docs.html
```

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

### CLI Dry-Run

Source: https://github.com/iagobalmeida/scalar_doc/blob/main/README.md

Preview the resolved configuration for the CLI without generating the output file by using the --dry-run flag.

```bash
scalar_doc path/to/openapi.json --dry-run
```

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

### Integrate with FastAPI

Source: https://github.com/iagobalmeida/scalar_doc/blob/main/README.md

Integrate Scalar DOC with a FastAPI application to serve OpenAPI documentation. Ensure to set docs_url and redoc_url to None in FastAPI to avoid conflicts. Access the documentation at the /docs endpoint.

```python
from fastapi import FastAPI, responses
from scalar_doc import ScalarDoc

DESCRIPTION = """
# Sidebar Section

## Sidebar SubSection

### Title

Content
"""

app = FastAPI(
    title="Test",
    description=DESCRIPTION,
    docs_url=None,
    redoc_url=None,
)
docs = ScalarDoc.from_spec(spec=app.openapi_url, mode="url")


@app.post("/foo")
def post_foo(a: str):
    return a + " - ok"


@app.get("/docs", include_in_schema=False)
def get_docs():
    docs_html = docs.to_html()
    return responses.HTMLResponse(docs_html)

```

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

### Generate HTML Docs from Remote OpenAPI URL

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Generate HTML documentation from a remote OpenAPI specification by providing the URL. The `--mode url` flag is used for remote URLs.

```bash
scalar_doc https://petstore3.swagger.io/api/v3/openapi.json --mode url --output petstore.html
```

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

### Programmatic Usage with OpenAPI URL

Source: https://github.com/iagobalmeida/scalar_doc/blob/main/README.md

Generate documentation from an OpenAPI specification located at a URL. You can set a custom title and configure appearance/behavior using ScalarConfiguration. The output is exported to an HTML file.

```python
from scalar_doc import ScalarDocs, ScalarConfiguration

# From URL
docs = ScalarDocs.from_spec("https://api.example.com/openapi.json", mode="url")
docs.set_title("My API Docs")

# Optional: configure appearance/behavior
docs.set_configuration(ScalarConfiguration(hide_sidebar=True))

# Export to HTML
docs.to_file("docs/index_from_url.html")

```

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

### Render API Docs to HTML String with ScalarDoc.to_html

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Generate the complete HTML document for API documentation as a string. This string can be directly served by web frameworks like Flask or Django, or written to a file. Allows customization of the target DOM element ID.

```python
from scalar_doc import ScalarDoc

docs = ScalarDoc.from_spec("https://petstore3.swagger.io/api/v3/openapi.json", mode="url")

# Default element ID "api-reference"
html = docs.to_html()

# Custom element ID
html_custom = docs.to_html(target_element_id="my-api-docs")

# Serve with Flask
from flask import Flask, Response
flask_app = Flask(__name__)

@flask_app.route("/docs")
def flask_docs():
    return Response(html, mimetype="text/html")

# Serve with Django
from django.http import HttpResponse
def django_docs(request):
    return HttpResponse(html, content_type="text/html")
```

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

### Export API Docs to File with ScalarDoc.to_file

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Write the rendered HTML API documentation to a specified file path. The function automatically creates any necessary parent directories for the output file. Includes verification steps to confirm file creation and content.

```python
from scalar_doc import ScalarDoc

docs = ScalarDoc.from_spec("https://petstore3.swagger.io/api/v3/openapi.json", mode="url")
docs.set_title("Petstore API Reference")

# Export to a nested path (parent dirs auto-created)
docs.to_file("output/docs/index.html")
# => output/docs/index.html is created and ready to open in a browser

# Verify
import os
assert os.path.exists("output/docs/index.html")
with open("output/docs/index.html", "r") as f:
    content = f.read()
    assert "Petstore API Reference" in content
```

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

### Create Custom Navigation Header

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Utilize ScalarHeader to add a sticky, branded header with a logo (supporting dark mode) and custom navigation links above the Scalar UI. Apply the header to a ScalarDoc instance.

```python
from scalar_doc import ScalarDoc, ScalarHeader

header = ScalarHeader(
    logo_url="https://example.com/logo.svg",
    logo_url_dark="https://example.com/logo-dark.svg",   # Optional dark-mode logo
    links={
        "Home": "https://example.com",
        "GitHub": "https://github.com/myorg/myrepo",
        "Support": "https://example.com/support",
    },
)

docs = ScalarDoc.from_spec("https://petstore3.swagger.io/api/v3/openapi.json", mode="url")
docs.set_header(header)
html = docs.to_html()

# The header is injected as sticky HTML above the Scalar component
assert 'class="custom-header scalar-app"' in html      # True
assert "https://example.com/logo-dark.svg" in html     # True
assert 'href="https://github.com/myorg/myrepo"' in html  # True
```

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

### Build API Docs with ScalarDoc

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Use ScalarDoc to generate API documentation from remote URLs, local JSON files, or raw dictionaries. The generated HTML can be printed or saved to a file. It can also be integrated with web frameworks like FastAPI.

```python
import json
from scalar_doc import ScalarDoc

# --- From a remote URL ---
docs = ScalarDoc.from_spec("https://petstore3.swagger.io/api/v3/openapi.json", mode="url")
html = docs.to_html()
print(html[:200])  # Full HTML page string

# --- From a local JSON file ---
with open("openapi.json", "r", encoding="utf-8") as f:
    spec = json.load(f)

docs = ScalarDoc.from_spec(spec, mode="json")
docs.set_title("My API Docs")
docs.to_file("docs/index.html")
# => Creates docs/index.html (directories created automatically)

# --- From a raw dict (e.g., FastAPI's app.openapi()) ---
from fastapi import FastAPI
app = FastAPI(title="Inventory API", docs_url=None, redoc_url=None)

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

docs = ScalarDoc.from_spec(app.openapi_url, mode="url")

@app.get("/docs", include_in_schema=False)
def get_docs():
    from fastapi.responses import HTMLResponse
    return HTMLResponse(docs.to_html())
# => Visit /docs to see live Scalar UI
```

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

### Customize Scalar Visual Theme

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Employ ScalarTheme to define the overall visual appearance, including logos and color schemes for light and dark modes. Set the theme on a ScalarDoc instance.

```python
from scalar_doc import ScalarDoc, ScalarTheme, ScalarColorSchema

theme = ScalarTheme(
    favicon_url="https://example.com/favicon.ico",
    logo_url="https://example.com/logo-light.png",
    logo_url_dark="https://example.com/logo-dark.png",
    color_scheme_light=ScalarColorSchema(
        color_1="#191414",
        color_2="#3e3e3e",
        color_3="#1DB954",
        color_accent="#1DB954",
        background_1="#ffffff",
        background_2="#f0f0f0",
        background_3="#e6e6e6",
        background_accent="#d2fbe3",
        link_color="#1DB954",
        code="#2b2b2b",
    ),
    color_scheme_dark=ScalarColorSchema(
        color_1="#ffffff",
        color_2="#aaaaaa",
        color_3="#1DB954",
        color_accent="#1DB954",
        background_1="#191414",
        background_2="#121212",
        background_3="#282828",
        background_accent="#1DB95433",
        link_color="#1DB954",
        code="#1DB954",
    ),
)

docs = ScalarDoc.from_spec("https://petstore3.swagger.io/api/v3/openapi.json", mode="url")
docs.set_theme(theme)
html = docs.to_html()
assert "--scalar-color-accent: #1DB954" in html  # True
```

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

### Update OpenAPI Spec with ScalarDoc.set_spec

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Dynamically change the OpenAPI specification source for an existing ScalarDoc instance. Supports switching between URL-based and inline JSON specifications.

```python
from scalar_doc import ScalarDoc

docs = ScalarDoc()

# Switch to a URL-based spec
docs.set_spec("https://api.example.com/openapi.json", mode="url")

# Switch to an inline JSON spec
spec_dict = {
    "openapi": "3.0.0",
    "info": {"title": "Sample API", "version": "1.0.0"},
    "paths": {
        "/hello": {
            "get": {
                "summary": "Say Hello",
                "responses": {"200": {"description": "OK"}},
            }
        }
    },
}
docs.set_spec(spec_dict, mode="json")
html = docs.to_html()
assert "Sample API" in html  # True
```

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

### Define Fine-grained Color Schema

Source: https://context7.com/iagobalmeida/scalar_doc/llms.txt

Use ScalarColorSchema to specify detailed color properties for light or dark modes, mapping directly to Scalar CSS variables. These schemas are used within ScalarTheme.

```python
from scalar_doc import ScalarColorSchema, ScalarTheme, ScalarDoc

# GitHub-inspired dark theme
dark = ScalarColorSchema(
    color_1="#e6edf3",        # --scalar-color-1 (primary text)
    color_2="#8d96a0",        # --scalar-color-2 (secondary text)
    color_3="#58a6ff",        # --scalar-color-3 (tertiary / highlights)
    color_accent="#58a6ff",   # --scalar-color-accent (interactive elements)
    background_1="#0d1117",   # --scalar-background-1 (page bg)
    background_2="#161b22",   # --scalar-background-2 (card/sidebar bg)
    background_3="#21262d",   # --scalar-background-3 (hover states)
    background_accent="#388bfd26",  # --scalar-background-accent
    link_color="#58a6ff",     # --scalar-link-color
    code="#f0883e",           # code element color
)

light = ScalarColorSchema(
    color_1="#1f2328", color_2="#636c76", color_3="#0969da",
    color_accent="#0969da", background_1="#ffffff", background_2="#f6f8fa",
    background_3="#eaeef2", background_accent="#0969da1a",
    link_color="#0969da", code="#953800",
)

theme = ScalarTheme(color_scheme_light=light, color_scheme_dark=dark)
docs = ScalarDoc.from_spec("https://petstore3.swagger.io/api/v3/openapi.json", mode="url")
docs.set_theme(theme)
docs.to_file("github-style-docs.html")
```

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