summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorTom Hiller <thrilleratplay@gmail.com>2018-07-28 17:38:54 -0400
committerPhilipp Deppenwiese <zaolin.daisuki@gmail.com>2018-09-30 03:18:05 +0000
commitffe6d5415186ece9577c3bfad6d0fc8dd653705e (patch)
tree6155b4cef0ceb4dfde3a04608e75d667d9563fc6 /Documentation
parente180825080ae13e990ef4b789806a02b0cc1eda5 (diff)
downloadcoreboot-ffe6d5415186ece9577c3bfad6d0fc8dd653705e.tar.xz
Documentation: Disable auto_doc_ref
According to recommonmark's documentation the enable_auto_doc_ref is deprecated. This is not true, as it's broken with Sphinx 1.6+ commit 12d639873953847de31ec99742b42e50e89ed58c. recommonmark bug report is here: https://github.com/rtfd/recommonmark/issues/73 Instead of using this feature, which doesn't support top level directories in the relative document path anyway, use the TOC tree or inline RST code. Disable auto_doc_ref and document how to reference documents. Change-Id: I9319985b504c4215c33ebbeb9c38317b9efcb283 Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com> Reviewed-on: https://review.coreboot.org/28550 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Tom Hiller <thrilleratplay@gmail.com> Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/conf.py2
-rw-r--r--Documentation/getting_started/writing_documentation.md8
2 files changed, 9 insertions, 1 deletions
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