Research CommonsResearch Commons
docparser/Quickstart

Quickstart

Set up a workspace, parse a single file or a whole directory, and optionally caption figures with docparser.

This walkthrough assumes you've finished Installation (pip install 'rc-docparser[all]' is the easiest start).

The workspace layout

docparser organizes input and output under a single root using a WorkspaceLayout:

<root>/
├── data/raw/        # put your source documents here
├── data/parsed/     # Markdown + JSON output
├── data/assets/     # extracted images
└── .cache/          # VLM caption cache

1. Parse a whole directory

Drop documents into data/raw/, then:

from docparser import WorkspaceLayout, run_all
 
layout = WorkspaceLayout.under("./project")   # data/raw, data/parsed, data/assets, .cache
layout.ensure()
 
run_all(layout, use_vlm=False)                # parse everything in data/raw

run_all walks data/raw/, parses every supported file, and writes a top-level CORPUS.md plus data/parsed/corpus.json.

2. Parse a single file

from docparser import parse_path, WorkspaceLayout
 
layout = WorkspaceLayout.under(".")
payload = parse_path("paper.pdf", layout)
print(payload["stats"])

parse_path dispatches by file extension, returning a payload dict (and writing document.md / document.json unless you disable output).

3. Caption figures with a VLM (optional)

Enable vision-language captioning to describe every extracted figure. The default provider is OpenRouter:

import os
os.environ["OPENROUTER_API_KEY"] = "sk-or-v1-..."
 
run_all(layout, use_vlm=True, max_images=50)

See Image captioning (VLM) for providers and the caption schema.

Next