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:
parent
ecdbc842e2
commit
f664321508
|
@ -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 =
|
||||||
|
|
|
@ -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,
|
||||||
|
|
10
Makefile
10
Makefile
|
@ -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
|
||||||
|
|
Loading…
Reference in New Issue