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>
This commit is contained in:
Patrick Rudolph 2020-05-17 20:04:12 +02:00 committed by Patrick Georgi
parent ecdbc842e2
commit f664321508
3 changed files with 37 additions and 4 deletions

View File

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

View File

@ -1,6 +1,18 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
import subprocess import subprocess
from recommonmark.parser import CommonMarkParser 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. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
@ -25,7 +37,18 @@ release = subprocess.check_output(('git', 'describe')).decode("utf-8")
# The short X.Y version. # The short X.Y version.
version = release.split("-")[0] 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 # The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages. # for a list of supported languages.
@ -187,7 +210,9 @@ class MyCommonMarkParser(CommonMarkParser):
def setup(app): def setup(app):
from recommonmark.transform import AutoStructify 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', { app.add_config_value('recommonmark_config', {
'enable_auto_toc_tree': True, 'enable_auto_toc_tree': True,

View File

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