GNUBoot
/
coreboot-kgpe-d16
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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>
This commit is contained in:
Tom Hiller 2018-07-28 17:38:54 -04:00 committed by Philipp Deppenwiese
parent e180825080
commit ffe6d54151
2 changed files with 9 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/conf.py
View File

@ -183,7 +183,7 @@ def setup(app):
from recommonmark.transform import AutoStructify from recommonmark.transform import AutoStructify
app.add_config_value('recommonmark_config', { app.add_config_value('recommonmark_config', {
'enable_auto_toc_tree': True, 'enable_auto_toc_tree': True,
'enable_auto_doc_ref': True, 'enable_auto_doc_ref': False, # broken in Sphinx 1.6+
'enable_eval_rst': True, 'enable_eval_rst': True,
'url_resolver': lambda url: '/' + url 'url_resolver': lambda url: '/' + url
}, True) }, True)

8
Documentation/getting_started/writing_documentation.md
View File

@ -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 You will also need python-recommonmark for sphinx to be able to handle
markdown documenation. markdown documenation.
The recommended version is sphinx 1.7.7, sphinx_rtd_theme 0.4.1 and
recommonmark 0.4.0.
### Optional ### Optional
Install [shpinx-autobuild] for rebuilding markdown/rst sources on the fly! 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 12. Shouldn't cover implementation details; for details, the code is the
reference. 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 ## Markdown and Tables
Under Sphinx markdown tables are not supported. Therefore you can use following Under Sphinx markdown tables are not supported. Therefore you can use following