Sphinx output, without the pipeline.
Sphinx has powered Python and C++ documentation since 2008. The ecosystem is deep. The setup cost, build times, and RST learning curve are not. Sourcey produces modern docs from Markdown and the same Doxygen XML — one tool, one config file.
Feature by feature.
Same capabilities. No monthly bill. Static HTML you own and deploy yourself.
| Sphinx | Sourcey | |
|---|---|---|
| Markup language | reStructuredText | Markdown |
| OpenAPI reference | Plugin | Native |
| C++ / Doxygen docs | Breathe + Exhale | Native (via XML) |
| Static HTML output | Yes | Yes |
| Zero JS runtime | No | Yes |
| Dev server | make html (manual) | Vite SSR hot-reload |
| Dark mode | Theme-dependent | Yes |
| Search | Basic text match | Instant fuzzy search |
| Config format | Python (conf.py) | TypeScript |
| Pricing | Free | Free |
What Sphinx costs you.
reStructuredText
Sphinx requires reStructuredText. RST is powerful, but the syntax is unintuitive — directives use double colons and indentation-sensitive blocks, roles use backtick-colon notation, and cross-referencing requires learning a domain-specific vocabulary. Every new contributor to your docs has to learn RST before they can write a paragraph.
MyST was created specifically to let people write Markdown instead of RST for Sphinx projects. But MyST sits on top of Sphinx — sphinx.ext.autodoc is hardcoded to expect RST in docstrings, and mixing markup languages between docstrings and documentation is fragile. Read the Docs published a migration guide acknowledging the friction. Sourcey uses standard Markdown with directive extensions that work everywhere.
Slow builds
Sphinx rebuilds are slow on large projects. The Godot engine documentation — 1,652 RST files, ~34 MB of content — takes approximately one hour to build with Sphinx, regularly timing out on Read the Docs. Profiling showed 30% of build time is spent copying nodes that are immediately pruned. Every documentation change means waiting minutes before you can review it.
Sphinx issue #14277 documents the Godot build time problem in detail. The Kedro project opened an issue to explore alternatives to Sphinx and Read the Docs specifically because "locally modifying docs takes multiple minutes to render/preview simple changes" and the situation had "worsened over time." Sourcey uses Vite with SSR hot-reload — changes appear in milliseconds.
The 4-tool C++ pipeline
If you need modern-looking C++ docs with Sphinx, the standard approach is Doxygen → Breathe → Exhale → Sphinx. Four tools, four configurations, four sets of version compatibility issues. Breathe reads Doxygen XML and exposes RST directives. Exhale auto-generates RST file hierarchies from Breathe output. Sphinx renders the final HTML. Microsoft's C++ blog documents this pipeline as a tutorial — the setup alone fills an article.
Exhale depends on Breathe, BeautifulSoup, and lxml for parsing Doxygen XML. Breathe requires Doxygen's XML output to be enabled separately. Each tool has its own configuration surface. Sourcey replaces Breathe, Exhale, and Sphinx with one config file. You keep Doxygen for parsing — it's battle-tested on OpenCV, Qt, Boost, and thousands of embedded projects. The problem was never the parsing.
Dated default output
Sphinx's default alabaster theme looks like it was designed in 2010 because it was. The community has built better themes — Furo, Read the Docs theme, Book theme — but each adds another dependency, another configuration surface, and another thing to maintain. None of them ship with instant fuzzy search, dark mode with design tokens, or zero-JS output.
The Read the Docs theme is the most popular Sphinx theme and it's serviceable, but it still ships a JavaScript runtime and requires pip-installing a theme package. Furo is better-looking but equally requires a Python environment. Sourcey ships three built-in presets — sidebar + TOC, minimal single column, and API-first three column — with dark mode and instant search out of the box.
One command. Five minutes.
Sourcey reads Markdown. If you have Doxygen XML, it reads that too. No RST conversion required — just bring your content.
Init
Creates sourcey.config.ts and detects any OpenAPI specs or Doxyfiles in the project.
npx sourcey initConvert your content
RST files need to become Markdown. For most projects this is straightforward — headings, lists, code blocks, and links translate directly. Sphinx-specific directives (.. toctree::, roles) get replaced with Sourcey's Markdown directives.
# Sphinx RST
.. note::
This is a callout.
.. code-block:: python
client = SDK()
# Sourcey Markdown
:::note
This is a callout.
:::
```python
client = SDK()
```Configure
Navigation, tabs, spec paths. TypeScript with autocomplete.
import { defineConfig } from "sourcey";
export default defineConfig({
name: "Your Project",
navigation: {
tabs: [
{
tab: "Documentation",
groups: [
{
group: "Getting Started",
pages: ["introduction", "quickstart"],
},
],
},
{
tab: "API Reference",
doxygen: {
xml: "./build/doxygen/xml",
language: "cpp",
},
},
],
},
});Build
Outputs static HTML to dist/. Deploy wherever.
$ npx sourcey build
Sourcey — building documentation site
Pages: 36
Output: dist
Time: 1.8sCommon questions.
Does Sourcey replace Sphinx for Python autodoc?
No. Sphinx's autodoc extension introspects live Python objects to generate API docs from docstrings. Sourcey doesn't do this. If you rely on autodoc for Python API reference, Sphinx is the right tool. If your docs are primarily written guides, OpenAPI reference, or C++ API docs via Doxygen, Sourcey handles all of those.
Can I use my existing Doxygen setup?
Yes. If you're using the Doxygen → Breathe → Exhale → Sphinx pipeline, Sourcey replaces Breathe, Exhale, and Sphinx. Keep your Doxyfile and comments. Enable XML output, point Sourcey at the XML directory, and build. One config file replaces three tools.
Do I have to convert all my RST to Markdown?
Yes. Sourcey uses Markdown with directive extensions. RST doesn't transfer directly. For most documentation the conversion is mechanical — headings, lists, code blocks, links, and admonitions all have direct equivalents. Sphinx-specific constructs like toctree and domain roles don't have 1:1 mappings but are replaced by Sourcey's navigation config and Markdown directives.
Is Sphinx more powerful than Sourcey?
In some ways, yes. Sphinx has a massive extension ecosystem, Python autodoc, and reStructuredText's full directive system. If you need those, use Sphinx. Sourcey is opinionated toward a specific output: modern, searchable, dark-mode-ready documentation sites for APIs and developer tools. It does that one thing with less setup.
What about MkDocs?
MkDocs is the most common Sphinx alternative in the Python ecosystem. It uses Markdown and has a solid theme (Material). But MkDocs doesn't have native OpenAPI support, doesn't read Doxygen XML, ships a JavaScript runtime, and uses YAML config. If you need API reference docs or C++ support, Sourcey covers ground MkDocs doesn't.
Does Sourcey support Sphinx extensions?
No. Sphinx extensions are Python packages that hook into Sphinx's build pipeline. They don't work with Sourcey. Sourcey has its own feature set — OpenAPI, MCP, Doxygen, rich Markdown components, instant search, dark mode, llms.txt — but it's a different tool, not a Sphinx-compatible drop-in.
Own your docs.
Open source. Self-host it, fork it, ship it on your own infrastructure. No account required.
Fork the demo →