Documentation: Add several fixes
* Add support for Sphinx 3.0+
* Add backward support for Sphinx 1.8 and older
* Make sphinxcontrib ditaa an optional extension
* Allow SPHINXOPTS to be set from command line
* Add sphinx and sphinx-lint to top level Makefile
Change-Id: If10aef51dc426445cb742aad13b19ee7fe169c51
Signed-off-by: Patrick Rudolph <siro@das-labor.org>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/41492
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 8848ee6..f82fa0e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -1,6 +1,18 @@
# -*- coding: utf-8 -*-
import subprocess
from recommonmark.parser import CommonMarkParser
+import sphinx
+
+# Get Sphinx version
+major = 0
+minor = 0
+patchlevel = 0
+version = sphinx.__version__.split(".")
+if len(version) > 1:
+ major = int(version[0])
+ minor = int(version[1])
+ if len(version) > 2:
+ patchlevel = int(version[2])
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -25,7 +37,18 @@
# The short X.Y version.
version = release.split("-")[0]
-extensions = ['sphinxcontrib.ditaa']
+extensions = []
+# Load recommonmark, supported since 1.8+
+if major >= 2 or (major == 1 and minor >= 8):
+ extensions += ['recommonmark']
+
+# Try to load DITAA
+try:
+ import sphinxcontrib.ditaa
+except ImportError:
+ print("Error: Please install sphinxcontrib.ditaa for ASCII art conversion\n")
+else:
+ extensions += 'sphinxcontrib.ditaa'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -187,7 +210,9 @@
def setup(app):
from recommonmark.transform import AutoStructify
- app.add_source_parser('.md', MyCommonMarkParser)
+ # Load recommonmark on old Sphinx
+ if major == 1 and minor < 8:
+ app.add_source_parser('.md', MyCommonMarkParser)
app.add_config_value('recommonmark_config', {
'enable_auto_toc_tree': True,