From ffe6d5415186ece9577c3bfad6d0fc8dd653705e Mon Sep 17 00:00:00 2001 From: Tom Hiller Date: Sat, 28 Jul 2018 17:38:54 -0400 Subject: 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 Reviewed-on: https://review.coreboot.org/28550 Tested-by: build bot (Jenkins) Reviewed-by: Tom Hiller Reviewed-by: Philipp Deppenwiese --- Documentation/conf.py | 2 +- Documentation/getting_started/writing_documentation.md | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) 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 -- cgit v1.2.3