<p>Patrick Rudolph has uploaded this change for <strong>review</strong>.</p><p><a href="https://review.coreboot.org/28550">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">Documentation: Disable auto_doc_ref<br><br>According to recommonmark's documentation the enable_auto_doc_ref is deprecated.<br>This is not true, as it's broken with Sphinx 1.6+ commit<br>12d639873953847de31ec99742b42e50e89ed58c.<br><br>recommonmark bug report is here: https://github.com/rtfd/recommonmark/issues/73<br><br>Instead of using this feature, which doesn't support top level directories in<br>the relative document path anyway, use the TOC tree or inline RST code.<br><br>Disable auto_doc_ref and document how to reference documents.<br><br>Change-Id: I9319985b504c4215c33ebbeb9c38317b9efcb283<br>Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com><br>---<br>M Documentation/conf.py<br>M Documentation/getting_started/writing_documentation.md<br>2 files changed, 9 insertions(+), 1 deletion(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://review.coreboot.org:29418/coreboot refs/changes/50/28550/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/Documentation/conf.py b/Documentation/conf.py</span><br><span>index ff1ad9d..07868fa 100644</span><br><span>--- a/Documentation/conf.py</span><br><span>+++ b/Documentation/conf.py</span><br><span>@@ -183,7 +183,7 @@</span><br><span>     from recommonmark.transform import AutoStructify</span><br><span>     app.add_config_value('recommonmark_config', {</span><br><span>         'enable_auto_toc_tree': True,</span><br><span style="color: hsl(0, 100%, 40%);">-        'enable_auto_doc_ref': True,</span><br><span style="color: hsl(120, 100%, 40%);">+        'enable_auto_doc_ref': False, # broken in Sphinx 1.6+</span><br><span>         'enable_eval_rst': True,</span><br><span>         'url_resolver': lambda url: '/' + url</span><br><span>     }, True)</span><br><span>diff --git a/Documentation/getting_started/writing_documentation.md b/Documentation/getting_started/writing_documentation.md</span><br><span>index 027def9..d57244a 100644</span><br><span>--- a/Documentation/getting_started/writing_documentation.md</span><br><span>+++ b/Documentation/getting_started/writing_documentation.md</span><br><span>@@ -20,6 +20,9 @@</span><br><span> You will also need python-recommonmark for sphinx to be able to handle</span><br><span> markdown documenation.</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+The recommended version is sphinx 1.7.7, sphinx_rtd_theme 0.4.1 and</span><br><span style="color: hsl(120, 100%, 40%);">+recommonmark 0.4.0.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> ### Optional</span><br><span> </span><br><span> Install [shpinx-autobuild] for rebuilding markdown/rst sources on the fly!</span><br><span>@@ -47,6 +50,11 @@</span><br><span> 12.  Shouldn't cover implementation details; for details, the code is the</span><br><span>      reference.</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+## Referencing markdown documents</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Starting with Sphinx 1.6 recommonmark's *auto_doc_ref* feature is broken.</span><br><span style="color: hsl(120, 100%, 40%);">+To reference documents use the TOC tree or inline RST code.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> ## Markdown and Tables</span><br><span> </span><br><span> Under Sphinx markdown tables are not supported. Therefore you can use following</span><br><span></span><br></pre><p>To view, visit <a href="https://review.coreboot.org/28550">change 28550</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://review.coreboot.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://review.coreboot.org/28550"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: coreboot </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>
<div style="display:none"> Gerrit-Change-Id: I9319985b504c4215c33ebbeb9c38317b9efcb283 </div>
<div style="display:none"> Gerrit-Change-Number: 28550 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: Patrick Rudolph <patrick.rudolph@9elements.com> </div>
<div style="display:none"> Gerrit-Reviewer: Tom Hiller <thrilleratplay@gmail.com> </div>