Docyard vs. Sphinx
An honest comparison of Docyard and Sphinx — the scientific-Python documentation incumbent.
Docyard vs. Sphinx
Sphinx is the incumbent for scientific and technical documentation. The entire scientific-Python ecosystem — NumPy, SciPy, pandas, Python itself — is built on it. This is the comparison where Docyard's edge is narrowest, because most of Docyard's scholarly features are things Sphinx has done well for over a decade.
At a glance
| Dimension | Docyard | Sphinx |
|---|---|---|
| Authoring format | Markdown, Quarto (.qmd), Jupyter (.ipynb) | reStructuredText (MyST adds Markdown) |
| Cross-references | Built-in, numbered, cross-document | Built-in (numfig/numref, :ref:/:doc:) |
| Citations | Built-in | Built-in (sphinxcontrib-bibtex) |
| Math | Built-in (KaTeX) | Built-in (MathJax / imgmath) |
| Python API | docyard extract (griffe) | autodoc + napoleon — the gold standard |
| Multi-language API | Python, Rust, TypeScript, OpenAPI in one CLI | Mostly Python; other languages via extensions |
| Toolchain | Nix flake, modern Nuxt frontend | Python/pip, classic themes (or Furo/RTD) |
| Localization | Not built in (roadmap) | Built-in (gettext workflow) |
| Ecosystem | Early-stage | Very large, mature extension ecosystem |
Be honest: Sphinx already does the scholarly part
If you came to Docyard for citations, numbered cross-references, and math, know that Sphinx has all of these natively and battle-tested:
- Cross-references —
numfig/numrefnumber figures, tables, and listings;:ref:and:doc:link anywhere in the project. This is mature. - Citations —
sphinxcontrib-bibtexrenders real BibTeX bibliographies. - Math — native MathJax.
- Python API —
autodoc+napoleonis the reference implementation for pulling docstrings into docs, and it is deeper than anything Docyard offers for Python alone.
So Docyard does not win on "scholarly features exist." It wins, if at all, on how you get them.
Where Docyard wins
- Markdown and Quarto instead of reStructuredText. Many authors find reST's directive syntax heavier than Markdown. Docyard's Quarto syntax stays close to Markdown while still giving you citations, callouts, and cross-references. (Sphinx can use MyST for Markdown, narrowing this gap.)
- One extractor for several languages. Sphinx's API story is Python-first;
Rust, TypeScript, and OpenAPI need separate extensions or external tools.
Docyard's single
docyard extractCLI covers Python, Rust, TypeScript, and OpenAPI with one consistent renderer — useful for polyglot repos. - Nix-native reproducibility. Docyard is a flake input with a pinned toolchain; in managed mode authors touch only content files. Sphinx leaves Python environment management to you.
- A modern frontend out of the box. Docyard ships a current Nuxt theme with built-in search backends and OG-image generation. Sphinx's default theme is dated (most projects adopt Furo or the Read the Docs theme).
Where Sphinx wins
- Maturity and trust. Two decades of use across the scientific world. Edge cases are solved; the behavior is predictable.
autodocdepth. The deepest Python docstring extraction available.- Extension ecosystem. Hundreds of mature extensions
(
sphinxcontrib-*, diagrams, domains for other languages, …). - reStructuredText power. Directives, roles, and domains give fine-grained semantic markup that Markdown does not natively express.
- Built-in localization. A mature
gettext-based translation workflow. Docyard has none yet.
Decision guide
Choose Docyard if you want Markdown/Quarto authoring over reST, need multi-language (not just Python) API reference from one tool, already use Nix, and want a modern frontend without assembling a theme.
Choose Sphinx if you are a Python project that wants the deepest, most trusted API extraction, you need its huge extension ecosystem, you need mature localization, or reStructuredText's semantic power matters to you.