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>

Documentation/Makefile.sphinx

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS        =
+SPHINXOPTS        ?=
 SPHINXBUILD       = sphinx-build
 SPHINXAUTOBUILD   = sphinx-autobuild
 PAPER             =

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 @@ release = subprocess.check_output(('git', 'describe')).decode("utf-8")
 # 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 @@ class MyCommonMarkParser(CommonMarkParser):
 
 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,

Makefile

@@ -83,6 +83,8 @@ help_coreboot help::
 	@echo  '  distclean             - Remove build artifacts and config files'
 	@echo  '  doxygen               - Build doxygen documentation for coreboot'
 	@echo  '  doxyplatform          - Build doxygen documentation for the current platform'
+	@echo  '  sphinx                - Build sphinx documentation for coreboot'
+	@echo  '  sphinx-lint           - Build sphinx documenttion for coreboot with warnings as errors'
 	@echo  '  filelist              - Show files used in current build'
 	@echo  '  printall              - print makefile info for debugging'
 	@echo  '  gitconfig             - set up git to submit patches to coreboot'
@@ -419,6 +421,12 @@ cscope-project: clean-cscope $(obj)/project_filelist.txt
 cscope:
 	cscope -bR
 
+sphinx:
+	$(MAKE) -C Documentation -f Makefile.sphinx html
+
+sphinx-lint:
+	$(MAKE) SPHINXOPTS=-W -C Documentation -f Makefile.sphinx html
+
 doxy: doxygen
 doxygen:
 	$(DOXYGEN) Documentation/Doxyfile.coreboot
@@ -465,5 +473,5 @@ distclean: clean clean-ctags clean-cscope distclean-payloads distclean-utils
 	rm -rf coreboot-builds coreboot-builds-chromeos
 	rm -f abuild*.xml junit.xml* util/lint/junit.xml
 
-.PHONY: $(PHONY) clean clean-for-update clean-cscope cscope distclean doxygen doxy doxygen_simple
+.PHONY: $(PHONY) clean clean-for-update clean-cscope cscope distclean doxygen doxy doxygen_simple sphinx sphinx-lint
 .PHONY: ctags-project cscope-project clean-ctags