[coreboot-gerrit] Change in coreboot[master]: Documentation: Disable auto_doc_ref
Patrick Rudolph (Code Review)
gerrit at coreboot.org
Mon Sep 10 17:50:57 CEST 2018
Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/28550
Change subject: Documentation: Disable auto_doc_ref
......................................................................
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 at 9elements.com>
---
M Documentation/conf.py
M Documentation/getting_started/writing_documentation.md
2 files changed, 9 insertions(+), 1 deletion(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/50/28550/1
diff --git a/Documentation/conf.py b/Documentation/conf.py
index ff1ad9d..07868fa 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -183,7 +183,7 @@
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 027def9..d57244a 100644
--- a/Documentation/getting_started/writing_documentation.md
+++ b/Documentation/getting_started/writing_documentation.md
@@ -20,6 +20,9 @@
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 @@
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
--
To view, visit https://review.coreboot.org/28550
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-MessageType: newchange
Gerrit-Change-Id: I9319985b504c4215c33ebbeb9c38317b9efcb283
Gerrit-Change-Number: 28550
Gerrit-PatchSet: 1
Gerrit-Owner: Patrick Rudolph <patrick.rudolph at 9elements.com>
Gerrit-Reviewer: Tom Hiller <thrilleratplay at gmail.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.coreboot.org/pipermail/coreboot-gerrit/attachments/20180910/f2f171be/attachment-0001.html>
More information about the coreboot-gerrit
mailing list