Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/41492 )
Change subject: Documenation: Add several fixes ......................................................................
Documenation: Add several fixes
* Add support for Sphinx 3.0+ * Add backward support for Sphinx 1.8 and older * Make sphinxcontrib ditaa an option 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 --- M Documentation/Makefile.sphinx M Documentation/conf.py M Makefile 3 files changed, 37 insertions(+), 4 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/92/41492/1
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index caa8190..6930130 100644 --- a/Documentation/Makefile.sphinx +++ b/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 = 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, diff --git a/Makefile b/Makefile index 55d3db1..ea21131 100644 --- a/Makefile +++ b/Makefile @@ -113,6 +113,8 @@ @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' @@ -449,6 +451,12 @@ 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 @@ -495,5 +503,5 @@ 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
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41492 )
Change subject: Documenation: Add several fixes ......................................................................
Patch Set 1:
(1 comment)
https://review.coreboot.org/c/coreboot/+/41492/1/Documentation/conf.py File Documentation/conf.py:
https://review.coreboot.org/c/coreboot/+/41492/1/Documentation/conf.py@49 PS1, Line 49: print("Error: Please install sphinxcontrib.ditaa for ASCII art conversion\n") It looks like it will continue despite the error? Adding
… the final result might be incorrect.
or something similar might be useful.
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41492 )
Change subject: Documenation: Add several fixes ......................................................................
Patch Set 1: Code-Review+1
(2 comments)
https://review.coreboot.org/c/coreboot/+/41492/1//COMMIT_MSG Commit Message:
https://review.coreboot.org/c/coreboot/+/41492/1//COMMIT_MSG@9 PS1, Line 9: * Add support for Sphinx 3.0+ Shorter:
Support Sphinx 3.0+
https://review.coreboot.org/c/coreboot/+/41492/1//COMMIT_MSG@11 PS1, Line 11: * Make sphinxcontrib ditaa an option extension optional
Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41492 )
Change subject: Documenation: Add several fixes ......................................................................
Patch Set 1:
(1 comment)
https://review.coreboot.org/c/coreboot/+/41492/1/Documentation/conf.py File Documentation/conf.py:
https://review.coreboot.org/c/coreboot/+/41492/1/Documentation/conf.py@49 PS1, Line 49: print("Error: Please install sphinxcontrib.ditaa for ASCII art conversion\n")
It looks like it will continue despite the error? Adding […]
Technically it won't be incorrect. The ASCII art is still usable, but not as pretty.
Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41492 )
Change subject: Documenation: Add several fixes ......................................................................
Patch Set 1: Code-Review+2
Angel Pons has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41492 )
Change subject: Documenation: Add several fixes ......................................................................
Patch Set 1:
(1 comment)
https://review.coreboot.org/c/coreboot/+/41492/1//COMMIT_MSG Commit Message:
https://review.coreboot.org/c/coreboot/+/41492/1//COMMIT_MSG@7 PS1, Line 7: Documenation Documen*t*ation
Hello build bot (Jenkins), Patrick Georgi, Martin Roth, Paul Menzel,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/41492
to look at the new patch set (#2).
Change subject: Documentation: Add several fixes ......................................................................
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 --- M Documentation/Makefile.sphinx M Documentation/conf.py M Makefile 3 files changed, 37 insertions(+), 4 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/92/41492/2
Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41492 )
Change subject: Documentation: Add several fixes ......................................................................
Patch Set 2:
(2 comments)
https://review.coreboot.org/c/coreboot/+/41492/1//COMMIT_MSG Commit Message:
https://review.coreboot.org/c/coreboot/+/41492/1//COMMIT_MSG@7 PS1, Line 7: Documenation
Documen*t*ation
Done
https://review.coreboot.org/c/coreboot/+/41492/1//COMMIT_MSG@11 PS1, Line 11: * Make sphinxcontrib ditaa an option extension
optional
Done
Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/41492 )
Change subject: Documentation: Add several fixes ......................................................................
Patch Set 2: Code-Review+2
Patrick Georgi has submitted this change. ( https://review.coreboot.org/c/coreboot/+/41492 )
Change subject: Documentation: Add several fixes ......................................................................
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 --- M Documentation/Makefile.sphinx M Documentation/conf.py M Makefile 3 files changed, 37 insertions(+), 4 deletions(-)
Approvals: build bot (Jenkins): Verified Patrick Georgi: Looks good to me, approved
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index caa8190..6930130 100644 --- a/Documentation/Makefile.sphinx +++ b/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 = 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, diff --git a/Makefile b/Makefile index d60f585..6a96f9d 100644 --- a/Makefile +++ b/Makefile @@ -83,6 +83,8 @@ @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: 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 @@ 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
-
Angel Pons (Code Review) -
Patrick Georgi (Code Review)
-
Patrick Rudolph (Code Review)
-
Paul Menzel (Code Review)