diff --git a/Documentation/conf.py b/Documentation/conf.py
index ff1ad9d8e2..07868faece 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -183,7 +183,7 @@ def setup(app):
     from recommonmark.transform import AutoStructify
     app.add_config_value('recommonmark_config', {
         'enable_auto_toc_tree': True,
-        'enable_auto_doc_ref': True,
+        'enable_auto_doc_ref': False, # broken in Sphinx 1.6+
         'enable_eval_rst': True,
         'url_resolver': lambda url: '/' + url
     }, True)
diff --git a/Documentation/getting_started/writing_documentation.md b/Documentation/getting_started/writing_documentation.md
index 027def96a1..d57244a72f 100644
--- a/Documentation/getting_started/writing_documentation.md
+++ b/Documentation/getting_started/writing_documentation.md
@@ -20,6 +20,9 @@ Please follow this official [guide] to install sphinx.
 You will also need python-recommonmark for sphinx to be able to handle
 markdown documenation.
 
+The recommended version is sphinx 1.7.7, sphinx_rtd_theme 0.4.1 and
+recommonmark 0.4.0.
+
 ### Optional
 
 Install [shpinx-autobuild] for rebuilding markdown/rst sources on the fly!
@@ -47,6 +50,11 @@ Documentation:
 12.  Shouldn't cover implementation details; for details, the code is the
      reference.
 
+## Referencing markdown documents
+
+Starting with Sphinx 1.6 recommonmark's *auto_doc_ref* feature is broken.
+To reference documents use the TOC tree or inline RST code.
+
 ## Markdown and Tables
 
 Under Sphinx markdown tables are not supported. Therefore you can use following