Supported Input Formats¶
Currently, doc2dash
supports two documentation formats:
Feel free to help adding more! While doc2dash
is implemented in Python, the scope for the supported documentation types is unlimited.
So go on and submit a parser for your favourite Ruby, Haskell, Lisp, Erlang, JavaScript, … format!
Sphinx¶
Sphinx is a very common documentation format in the Python world and beyond.
doc2dash
offers two approaches to parsing it.
The preferable one is used whenever a machine-readable intersphinx index file is present and it results in very precise and reliable parsing.
If none is found, doc2dash
attempts to parse the HTML API index file (genindex.html
or genindex-all.html
).
Simply point doc2dash
at Sphinx’s HTML output (usually _build/html
if you built it yourself) and it will do the right thing.
Building Sphinx documentation is usually easy:
after installing the sphinx
package, cd
into their documentation directory (usually docs
or doc
) and enter make html
.
Warning
Do not attempt to run doc2dash
over pre-built HTML documentation downloaded from Read The Docs.
Those downloads aren’t direct equivalents of the actual, pristine builds and indexing will not work.
pydoctor¶
Contrary to Sphinx, pydoctor is not a complete documentation format. Instead, it’s focused on creating API documentation from Python docstrings. The most popular project employing is Twisted and its ecosystem.
Since pydoctor alas does not emit a machine-readable file, the nameIndex.html
is always parsed.
Fortunately, no theming is common in the pydoctor world, so the parsing is reliable nonetheless.