Elaborate on input formats

Author: hynek

README.rst

@@ -19,12 +19,14 @@ doc2dash: Create docsets for Dash.app and clones
 ``doc2dash`` is an MIT-licensed extensible `Documentation Set`_ generator intended to be used with the `Dash.app`_ API browser for OS X or one of its many clones.
 
 If you’ve never heard of Dash.app, you’re missing out:
-Together with ``doc2dash`` it’s all your API documentation at your fingertips!
+together with ``doc2dash`` it’s all your API documentation at your fingertips!
 
-``doc2dash``\ ’s documentation lives at `Read the Docs <http://doc2dash.readthedocs.org/>`_, the code on `GitHub <https://github.com/hynek/doc2dash>`_.
+``doc2dash``\ ’s documentation lives at `Read the Docs`_, the code on GitHub_.
 It’s tested on Python 2.7, 3.3+, and PyPy.
 Both Linux and OS X are supported although certain features are only available on OS X.
 
 
 .. _`Documentation Set`: https://developer.apple.com/legacy/library/documentation/DeveloperTools/Conceptual/Documentation_Sets/010-Overview_of_Documentation_Sets/docset_overview.html#//apple_ref/doc/uid/TP40005266-CH13-SW6
 .. _`Dash.app`: http://kapeli.com/dash/
+.. _`Read the Docs`: <http://doc2dash.readthedocs.org/>
+.. _`GitHub`:  https://github.com/hynek/doc2dash

docs/formats.rst

@@ -1,15 +1,43 @@
 Supported Input Formats
 =======================
 
-Currently, the following input formats are supported:
+Currently, ``doc2dash`` supports two documentation formats:
 
-- Sphinx_’s HTML output (nearly every single Python project out there)
-- pydoctor_’s HTML output (Twisted_!)
+- :ref:`Sphinx-sec`
+- :ref:`pydoctor-sec`
 
 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-sec:
+
+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.
+
+
+.. _pydoctor-sec:
+
+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.
+
+
 .. _Twisted: https://twistedmatrix.com/
 .. _pydoctor: https://launchpad.net/pydoctor
 .. _Sphinx:  http://sphinx-doc.org/
+.. _intersphinx: http://sphinx-doc.org/latest/ext/intersphinx.html

docs/installation.rst

@@ -12,6 +12,10 @@ Of course, you can also install it as usual using pip_::
 ``doc2dash`` runs on Python 2.7, and 3.3+, and PyPy.
 Both Linux and OS X are supported although certain features are only available on OS X.
 
+.. note::
+
+   For best performance when converting large pieces documentation, I *strongly* recommend using PyPy as the interpreter of choice.
+
 
 .. _clones:
 

docs/usage.rst

@@ -37,5 +37,4 @@ Hints
 For Sphinx, you get the best results using the intersphinx_ parser that is used automatically if a version 2 ``objects.inv`` file is present.
 This approach obviates parsing problems completely by using that machine readable file using Sphinx’s own APIs.
 
-.. _intersphinx: http://sphinx-doc.org/latest/ext/intersphinx.html
 .. _SQLite: http://www.sqlite.org/