opendocs

📚 OpenDocs

Convert GitHub READMEs, Markdown files, and Jupyter Notebooks into structured, multi-format documentation — instantly.

#opensource  |  #documentation  |  #markdown  |  #ai  |  #devtools  |  #python  |  #jupyter  |  #llm

What is OpenDocs?

OpenDocs (by ioteverythin) takes a GitHub repository README, local Markdown file, or Jupyter Notebook (.ipynb) and automatically generates beautiful, professional documentation in multiple formats:

What's New in v0.9.0

• Interactive Knowledge Graph -- Explorable HTML graph (vis.js) with search, filtering, god-node analysis, community clusters, provenance labels, and surprising connections
• Graph JSON Export -- Persistent graph.json with nodes, edges, communities, provenance, god nodes, surprising connections, and suggested questions. Query weeks later without re-processing
• Community Detection -- Label propagation clustering groups entities by edge density. No external dependencies
• Provenance Labels -- Every entity and relation tagged EXTRACTED, INFERRED, or AMBIGUOUS so you always know what was found vs guessed
• Suggested Questions -- 5 auto-generated questions the graph is uniquely positioned to answer, based on structural signals
• God Nodes & Surprising Connections -- Highest-degree hub entities and cross-type edges ranked by surprise score
• Knowledge Wiki Export -- Wikipedia-style linked Markdown articles: one per community, plus index and entity catalog. Inspired by Graphify --wiki
• Semantic Similarity Edges -- Entities co-occurring in the same section but with no structural link get automatic SIMILAR_TO edges, surfacing hidden conceptual connections
• Jupyter Notebook Ingestion -- Parse .ipynb files and convert markdown cells, code cells, and outputs into polished reports
• Parameterized Report Templates -- Inject project name, author, version, date, and organisation into document headers, footers, and title pages via --config YAML/JSON or CLI flags
• File Watcher + Auto-PR -- opendocs watch daemon monitors repos for changes and auto-regenerates docs; supports cron mode (--once) and automatic pull requests (--auto-pr)
• 5 LLM Providers -- OpenAI, Anthropic (Claude), Google (Gemini), Ollama (local), Azure OpenAI
• 25 Built-in Themes -- 15 original + 10 new modern themes (Aurora, Carbon, Lavender, Graphite, Obsidian, Coral, Zen, Nebula, Sand, Glacier)
• AI Reader Files -- Auto-generate llms.txt, llms-full.txt, AGENTS.md, and CLAUDE.md for LLMs and coding agents

Two Engines

1. Pipeline (Deterministic + LLM)

The core pipeline parses Markdown/Notebooks and generates all 12 selectable output formats:

• Basic mode -- Pure Markdown AST parsing, no LLM required. Fast, free, predictable.
• LLM mode -- Uses any supported LLM provider to extract entities, build knowledge graphs, and generate executive summaries + stakeholder views (CTO, Investor, Developer).

2. DocAgent (Agentic)

A full LangGraph-powered agent that generates 8 enterprise document types (PRD, Proposal, SOP, Report, Slides, Changelog, Onboarding, Tech Debt) from any GitHub repo.

Quick Start

Install from PyPI

pip install opendocs

For LLM features:

pip install opendocs[llm]

For all LLM providers:

pip install opendocs[all-providers]

For YAML config file support:

pip install opendocs[templates]

Install from source

git clone https://github.com/ioteverythin/OpenDocs.git
cd OpenDocs
pip install -e ".[dev,llm]"

Basic Usage

# Generate all formats from a GitHub README
opendocs generate https://github.com/owner/repo

# Generate specific format with a theme
opendocs generate https://github.com/owner/repo --format word --theme aurora

# From a local Markdown file
opendocs generate ./README.md --local

# LLM mode with knowledge graph + stakeholder summaries
opendocs generate ./README.md --local --mode llm --api-key sk-...

# Use Claude instead of OpenAI
opendocs generate ./README.md --local --mode llm --provider anthropic

# List available themes (25 themes)
opendocs themes

Incremental Builds

Generated artifacts are cached by content, so re-running the pipeline only rebuilds what actually changed. This matters most for opendocs watch, which otherwise regenerates every format on every save.

opendocs generate ./README.md --local              # cached automatically
opendocs generate ./README.md --local --no-cache   # force a full rebuild
opendocs generate ./README.md --local --cache-dir /tmp/od-cache

opendocs cache            # show location, entry count, and size
opendocs cache --clear    # empty it

The cache key covers the document content, the knowledge graph, the theme, the template variables, the output format, and the installed opendocs version, so changing any of them rebuilds rather than reusing. A cache hit reproduces the stored artifact byte for byte; the one thing it does not refresh is the generation timestamp, which is what makes identical inputs produce identical output.

LLM responses are cached too. In --mode llm, re-running over an unchanged README previously re-paid for every API call. Responses are now stored on disk keyed by provider, model, temperature, token limit, and the exact prompt, so a repeat run costs nothing and returns instantly:

opendocs generate ./README.md --local --mode llm    # first run calls the API
opendocs generate ./README.md --local --mode llm    # second run is free

export OPENDOCS_LLM_CACHE=0    # disable response caching only
opendocs generate ./README.md --local --mode llm --no-cache   # disable both

Note this deliberately trades novelty for cost and reproducibility: with temperature > 0 the provider would have returned a different answer, and you get the earlier one. Change the temperature, the model, or the prompt and it re-asks; use --no-cache when you specifically want a fresh generation.

What Changed Since the Last Release

opendocs diff compares two versions of your documentation and reports what moved — new and removed sections, concepts, and relationships — then renders it as release notes. Deterministic and offline.

# Two files
opendocs diff old/README.md new/README.md

# Two git revisions of the same file
opendocs diff v0.8.0 HEAD --git . --path README.md

# Two previously exported graphs
opendocs diff v1_graph.json v2_graph.json

# Draft release notes
opendocs diff v0.8.0 HEAD --git . --format markdown -o RELEASE_NOTES.md

# Machine-readable, including which formats are worth regenerating
opendocs diff old.md new.md --format json

# CI gate: fail if documentation drifted
opendocs diff committed.md generated.md --fail-on-change

The summary also reports which output formats are worth regenerating, so a docs pipeline can rebuild only what the change actually affects.

What Isn't Documented

opendocs lint checks the quality of what your docs say. opendocs coverage reports what they miss, by comparing the real API surface against what the documentation actually mentions:

opendocs coverage .                          # report
opendocs coverage . --show-missing           # list every gap
opendocs coverage . --fail-under 80          # CI gate
opendocs coverage . --json                   # machine-readable
opendocs coverage . --docs README.md --docs docs/guide.md

Dimension              Covered  Total  Coverage
docstrings:functions        87     88     98.9%
docstrings:classes         185    187     98.9%
env-vars                     4      7     57.1%
cli-flags                   41     76     53.9%
tech-stack                   4     14     28.6%
  Overall: 86.3%

Four dimensions are scored, each chosen because it has an objective answer: docstrings on public symbols, environment variables the code reads, CLI flags it defines, and detected technologies. Test files and private helpers are excluded by default (--include-tests, --include-private to include them), and the overall figure is weighted by item count so a single missed flag does not outweigh hundreds of documented symbols.

It deliberately does not judge whether prose is good — that is not objectively measurable, and a score nobody can verify is worse than none.

Everything runs offline with no LLM. Exit codes: 0 pass, 1 below --fail-under, 2 analysis failed.

Linting Documentation in CI

opendocs lint checks documentation quality and exits non-zero when it regresses, so a pull request can fail on a broken README the same way it fails on a broken test:

opendocs lint ./README.md --local                      # errors fail the build
opendocs lint ./README.md --local --fail-on warning    # be stricter
opendocs lint ./README.md --local --fail-on never      # report only
opendocs lint ./README.md --local --json               # machine-readable
opendocs lint https://github.com/owner/repo --check-links

All rules run offline; --check-links is the only one that uses the network.