# doc2dash: turning built documentation into Dash and Zeal docsets

> doc2dash converts a directory of already built intersphinx documentation into a docset, the indexed format that the Dash and Zeal API browsers search instantly. Its scope is narrow by design, and the thing to understand before you use it is that the documentation has to exist on disk first, which means the documentation build is part of your workflow whether you like it or not.

**hynek/doc2dash** — Create docsets for Dash.app-compatible API browsers.

- Repository: https://github.com/hynek/doc2dash
- Website: https://doc2dash.hynek.me/
- Stars: 600 · Forks: 36
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/hynek-doc2dash

## The gap is between the docs you have and the docsets you can search

doc2dash is an extensible Documentation Set generator, a docset generator, that helps you have documentation for all your favourite APIs in Dash-compatible API browsers.

The problem it solves is described concretely in the README. An API browser is an application that runs locally on your computer and lets you search various API docs by pressing a key combination and starting to type. The most common ones, Dash on macOS and Zeal on Windows and Linux, come with many docsets out of the box, but they can never offer you docsets for every package you will ever use.

That is where doc2dash comes in. It takes your offline documentation and converts it into an indexed format that API browsers can read and search, and the README is quick to add that this is very fast, which is the point of the indexed format.

The scope of the input is what makes the tool general. It supports all known intersphinx-based documentation systems, with Sphinx, pydoctor and MkDocs with mkdocstrings named. And while doc2dash is a Python project, the support is not limited to Python related formats, because the requirement is the intersphinx convention rather than the language of the project being documented.

The project is maintained by Hynek Schlawack, released under the MIT licence, and the development is supported by Variomedia AG and by GitHub Sponsors. The homepage is doc2dash.hynek.me, and the last push was on 2026-10-06 with the repository not archived.

## The input is built documentation, not a source tree

The one sentence in the quickstart that determines whether the tool works for you is this: point doc2dash at a directory containing built intersphinx-compatible documentation.

Built is the operative word. doc2dash is not a documentation generator, it does not run Sphinx, it does not parse Markdown, and it does not read a pyproject.toml to work out what to document. It reads the output of a documentation build that you have already produced, and it expects that output to follow the intersphinx conventions so it can find the objects, the links and the searchable text inside it.

That is a real constraint on how the tool fits into a workflow. If your project's documentation is built by Sphinx, by pydoctor or by MkDocs with mkdocstrings, then the build is already part of your release process, and doc2dash adds a step after it. If your documentation is something else entirely, a hand written site or a wiki, then there is no input for doc2dash, and the answer is a different tool or no tool.

The formats documentation linked from the project covers the specific rules of each supported system, and the README points to the usage page and a how-to for the options. The parser mechanism is also pluggable, which is the part that widens the scope again: the README states that you can write your own parser, and the project documentation has a page on extending it.

So the design has two layers. A set of built-in parsers for the intersphinx family, and an extension point for everything else.

## The quickstart is a Homebrew install and one command

The fastest way to get started is installing doc2dash from the maintainer's Homebrew tap.

```bash
$ brew install hynek/tap/doc2dash
```

If Homebrew is not an option, the README points at the project's installation instructions for the alternatives, which in practice means the PyPI package.

Then the tool is pointed at the built documentation directory.

```bash
$ doc2dash directory/to/documentation
```

The README describes the expected result: output like the one in the video it links, and an appropriately named docset appearing in the current directory. That last point is worth noting, because the docset is written into the working directory rather than into a location the tool picks, so where you run it from decides where the artefact lands. Once the file exists, it is added to Dash or Zeal the way any other docset is added.

The README also flags that doc2dash has many more features and options and points to the usage page for the details and a how-to page for the longer form.

For a tool that exists to save keystrokes, the whole quickstart is two commands, and that brevity is the point: the documentation ecosystem already produces the hard part, and the conversion into the browser format is the small remaining step.

## A small package with a modern build setup

The packaging tells you what kind of project this is.

The build backend is hatchling, with hatch-vcs for the version and hatch-fancy-pypi-readme for the readme, and both the version and the readme are declared dynamic, which means the version comes from the version control system rather than being written by hand. The project requires Python 3.10 or newer, and the classifiers list 3.10 through 3.14, with the development status marked as production and stable.

The runtime dependencies are four and short: attrs at 23.2 or newer, beautifulsoup4, click above version 8, and rich. The HTML parsing is done with beautifulsoup4, the command line with click, the terminal output with rich, and attrs carries the data structures. There is no documentation tool in that list, which is consistent with the design: doc2dash consumes built documentation, it does not build it.

The command line entry point is doc2dash = doc2dash.__main__:main, and the project URLs point at the documentation site, the changelog, the GitHub repository, a funding page and the maintainer's social accounts.

The development setup is equally conventional. There is a noxfile.py at the top level, and the dependency groups are split into tests with coverage and pytest, docs with zensical, mkdocstrings-python, mkdocs-click and markdown-callouts, typing with mypy and types-urllib3, and a dev group that includes the others plus nox. The pytest configuration is strict, the test paths point at tests, the import mode is importlib and warnings are filtered to be shown once. The coverage settings run in parallel with branch coverage enabled over the src directory, and the coverage paths are mapped so that the source and the installed copies in the nox environments line up.

The repository layout follows the src layout, with a src/ directory, a tests/ directory, a requirements/ directory, a docs/ directory, a .pre-commit-config.yaml, a .readthedocs.yaml and a zensical.toml for the documentation site.

## The extension point is the part that makes it extensible

The README puts extendability in the list of what the tool is, with a link to the extending page, and the claim is that you can write your own parser.

That is a meaningful design decision rather than a slogan. The built-in parsers cover the intersphinx family, and the family is defined by a convention rather than by a tool, so anything that produces that convention is in scope. A project documenting itself with a generator that is not in the list can add a parser rather than wait for the maintainers to write one.

The formats page linked from the README documents what each supported system means, which is the file to read first if you are adding a parser of your own, since the question is always which files hold the objects and which hold the text.

The practical value of the extension point is largest for teams with an internal or private package library. Those are exactly the packages that never get a published docset, because the vendor does not build one, and they are the reason the Dash and Zeal users reach for doc2dash in the first place. Writing a parser for a house documentation setup is a bounded piece of work, and the tool is built to allow it.

The trade is that a parser you write is a parser you maintain, and it has to keep working as the documentation generator changes its output.

## Where doc2dash is the wrong tool

Three cases, and they are different in kind.

The first is documentation that has not been built. If your project has no Sphinx, pydoctor or MkDocs build, or you have never run it, doc2dash has nothing to read. You either adopt a documentation generator that produces intersphinx output, which is a much larger decision than installing a converter, or you use a different approach.

The second is documentation that is already a docset. Many projects publish prebuilt docsets for Dash and Zeal, and when one exists for your package, converting it yourself adds nothing. The value of doc2dash is highest for the packages nobody has made a docset for, which is the same point the README makes about the browsers shipping many docsets but never every package.

The third is a team that wants search in a browser tab rather than in a desktop application. doc2dash targets API browsers, which are local applications with a key combination and a search box. A hosted documentation search, or a documentation site with a client side search index, solves a different problem and produces something shareable with a link rather than something installed per machine.

The underlying difference in approach is where the indexing happens. doc2dash runs on your machine, over documentation you have already built, and writes a local artefact. The alternative of a hosted search service indexes the documentation centrally and serves results over the network, which is shareable but requires a running service and a network round trip for every search.

## Release cadence, install channels and the licence

The project links its install channels clearly, and there are three of them: the Homebrew tap for macOS users, pre-compiled binaries published on the GitHub releases page, and the PyPI package. Each is a different answer to the same question for a different platform, and the README points at the installation instructions for the cases it does not cover.

The release history is short. The tags are 3.1.0 from 2024-01-15, 3.0.0 from 2022-09-13 and 2.4.1 from 2022-01-21. The last push was on 2026-10-06 and the repository is not archived, so the work is current even though the newest published version is more than two years old.

That gap is a fact to weigh rather than a reason to skip the tool. A converter like this changes rarely, because its input is a file format convention that moves slowly, and the 3.x line is the current line. What the gap does mean is that a bug fix may be sitting in the repository rather than in a release, so for a pinned environment the PyPI version and the git checkout are different things.

The licence is MIT, with the LICENSE file in the repository and the licence declared in the project metadata. That permits use, modification and redistribution, including inside commercial products, provided the notice travels with the code, and the project also carries a funding page and a changelog.

One detail in the metadata is worth a note for anyone pinning dependencies in a build. The runtime dependencies are declared with lower bounds rather than pinned versions, with attrs at 23.2 or newer, click above 8, and beautifulsoup4 and rich unbounded. For a tool whose output is a documentation artefact, an unbounded dependency in the parse path is the kind of thing that shows up as a surprise after an unrelated library release.

## Conclusion

doc2dash fits a developer whose packages never got a published docset and who already builds intersphinx documentation, and it does not fit a team with no documentation build or one that wants shareable hosted search instead of a local API browser. Before adopting it, build the documentation with Sphinx, pydoctor or MkDocs and run doc2dash over the output directory, then confirm the resulting docset appears in Dash or Zeal with the objects you expect to find.

## FAQ

### What does doc2dash do?

It takes offline documentation and converts it into an indexed docset format that Dash and Zeal compatible API browsers can read and search. Dash on macOS and Zeal on Windows and Linux ship with many docsets, but not for every package, and doc2dash fills that gap from documentation you build locally.

### Which documentation formats does doc2dash support?

It supports all known intersphinx based documentation systems, with Sphinx, pydoctor and MkDocs with mkdocstrings named explicitly. The README also notes that the support is not limited to Python related formats, because the requirement is the intersphinx convention, and you can write your own parser for other cases.

### How do I create a docset with doc2dash?

Install it, for example with brew install hynek/tap/doc2dash, then run doc2dash with the path to a directory of built intersphinx compatible documentation. The tool writes an appropriately named docset into the current directory, which you then add to Dash or Zeal.

### Does doc2dash build my documentation for me?

No. You point it at documentation that has already been built. The input has to be the output of a documentation build such as Sphinx, pydoctor or MkDocs with mkdocstrings, so the documentation build is part of your workflow either way.

### What are doc2dash's requirements and install options?

It requires Python 3.10 or newer, with runtime dependencies on attrs, beautifulsoup4, click and rich. You can install it from the maintainer's Homebrew tap, from pre-compiled binaries on the GitHub releases page, or from PyPI.

## Sources

- [hynek/doc2dash on GitHub](https://github.com/hynek/doc2dash)
- [License: MIT](https://github.com/hynek/doc2dash/blob/main/LICENSE)
- [Project website](https://doc2dash.hynek.me/)
- [README](https://github.com/hynek/doc2dash/blob/main/README.md)
- [Releases](https://github.com/hynek/doc2dash/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hynek-doc2dash