Re: [Intel-gfx] [maintainer-tools PATCH v2 4/4] doc: build documentation using Sphinx
On Thu, 10 Aug 2017, Rodrigo Vivi wrote: > On Thu, Aug 10, 2017 at 12:39:49PM +0300, Jani Nikula wrote: >> Based on Sphinx-quickstart, with existing and generated Makefiles merged >> together. >> >> This makes the rst2html and Sphinx builds work side by side. Plain >> 'make' continues to use rst2html, and 'make html' and friends use >> Sphinx. The intention is to keep both for a transition period so that we >> can have documentation autobuilders updated. >> >> Once we're fully converted to Sphinx, we can share the common parts of >> drm-intel and drm-misc documentation better, and have more coherent >> documentation overall. We can also start looking into using the graphviz >> (Sphinx builtin) and WaveDrom (3rd party) extensions. For now, we use >> the same old clunky methods for including them. >> >> v2: require Sphinx 1.3, use sphinx_rtd_theme > > Thanks! :) > > Acked-by: Rodrigo Vivi Thanks Rodrigo and Sean for the acks/reviews, pushed. BR, Jani. > >> >> Signed-off-by: Jani Nikula >> --- >> .gitignore | 1 + >> Makefile | 61 +++- >> conf.py| 236 >> + >> index.rst | 17 + >> 4 files changed, 313 insertions(+), 2 deletions(-) >> create mode 100644 conf.py >> create mode 100644 index.rst >> >> diff --git a/.gitignore b/.gitignore >> index 35ed071ca482..a176bd76eef5 100644 >> --- a/.gitignore >> +++ b/.gitignore >> @@ -1,3 +1,4 @@ >> +_build >> drm-intel-flow.svg >> drm-misc-commit-flow.svg >> *.html >> diff --git a/Makefile b/Makefile >> index 7059eec42720..40b7ee6e2b32 100644 >> --- a/Makefile >> +++ b/Makefile >> @@ -4,6 +4,20 @@ >> # the wavedrom json, copy-pasting to and from >> http://wavedrom.com/editor.html is >> # handy as it shows the result live. >> >> +# You can set these variables from the command line. >> +SPHINXOPTS= >> +SPHINXBUILD = sphinx-build >> +PAPER = >> +BUILDDIR = _build >> + >> +# Internal variables. >> +PAPEROPT_a4 = -D latex_paper_size=a4 >> +PAPEROPT_letter = -D latex_paper_size=letter >> +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) >> $(SPHINXOPTS) . >> +# the i18n builder cannot share the environment and doctrees with the others >> +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . >> + >> +.PHONY: all >> all: drm-intel.html dim.html drm-misc.html >> >> %.svg: %.dot >> @@ -41,7 +55,50 @@ mancheck: >> >> check: shellcheck mancheck all >> >> +.PHONY: clean >> clean: >> -rm -f drm-intel.html drm-intel-flow.svg drm-misc-commit-flow.svg >> dim.html drm-misc.html >> +rm -rf drm-intel.html drm-intel-flow.svg drm-misc-commit-flow.svg >> dim.html drm-misc.html $(BUILDDIR) >> + >> +.PHONY: help >> +help: >> +@echo "Please use \`make ' where is one of" >> +@echo " html to make standalone HTML files" >> +@echo " dirhtmlto make HTML files named index.html in directories" >> +@echo " singlehtml to make a single large HTML file" >> +@echo " linkcheck to check all external links for integrity" >> +@echo " doctestto run all doctests embedded in the documentation >> (if enabled)" >> + >> +# FIXME: This works for the first build, but not for updates. Look into >> using >> +# Sphinx extensions for both the graphviz and wavedrom parts. >> +html dirhtml singlehtml linkcheck doctest: drm-intel-flow.svg >> drm-misc-commit-flow.svg >> + >> +.PHONY: html >> +html: >> +$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html >> +@echo >> +@echo "Build finished. The HTML pages are in $(BUILDDIR)/html." >> + >> +.PHONY: dirhtml >> +dirhtml: >> +$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml >> +@echo >> +@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." >> + >> +.PHONY: singlehtml >> +singlehtml: >> +$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml >> +@echo >> +@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." >> + >> +.PHONY: linkcheck >> +linkcheck: >> +$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck >> +@echo >> +@echo "Link check complete; look for any errors in the above output " \ >> + "or in $(BUILDDIR)/linkcheck/output.txt." >> >> -.PHONY: all clean >> +.PHONY: doctest >> +doctest: >> +$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest >> +@echo "Testing of doctests in the sources finished, look at the " \ >> + "results in $(BUILDDIR)/doctest/output.txt." >> diff --git a/conf.py b/conf.py >> new file mode 100644 >> index ..385c2aa8ff66 >> --- /dev/null >> +++ b/conf.py >> @@ -0,0 +1,236 @@ >> +# -*- coding: utf-8 -*- >> +# >> +# DRM Maintainer Tools documentation build configuration file, created by >> +# sphinx-quickstart on Wed Aug 9 17:57:16 2017. >> +# >> +# This file is execfile()d with the current directory set to its >> +# containing dir. >> +# >> +# Note that not all possible c
Re: [Intel-gfx] [maintainer-tools PATCH v2 4/4] doc: build documentation using Sphinx
On Thu, Aug 10, 2017 at 12:39:49PM +0300, Jani Nikula wrote: > Based on Sphinx-quickstart, with existing and generated Makefiles merged > together. > > This makes the rst2html and Sphinx builds work side by side. Plain > 'make' continues to use rst2html, and 'make html' and friends use > Sphinx. The intention is to keep both for a transition period so that we > can have documentation autobuilders updated. > > Once we're fully converted to Sphinx, we can share the common parts of > drm-intel and drm-misc documentation better, and have more coherent > documentation overall. We can also start looking into using the graphviz > (Sphinx builtin) and WaveDrom (3rd party) extensions. For now, we use > the same old clunky methods for including them. > > v2: require Sphinx 1.3, use sphinx_rtd_theme Thanks! :) Acked-by: Rodrigo Vivi > > Signed-off-by: Jani Nikula > --- > .gitignore | 1 + > Makefile | 61 +++- > conf.py| 236 > + > index.rst | 17 + > 4 files changed, 313 insertions(+), 2 deletions(-) > create mode 100644 conf.py > create mode 100644 index.rst > > diff --git a/.gitignore b/.gitignore > index 35ed071ca482..a176bd76eef5 100644 > --- a/.gitignore > +++ b/.gitignore > @@ -1,3 +1,4 @@ > +_build > drm-intel-flow.svg > drm-misc-commit-flow.svg > *.html > diff --git a/Makefile b/Makefile > index 7059eec42720..40b7ee6e2b32 100644 > --- a/Makefile > +++ b/Makefile > @@ -4,6 +4,20 @@ > # the wavedrom json, copy-pasting to and from > http://wavedrom.com/editor.html is > # handy as it shows the result live. > > +# You can set these variables from the command line. > +SPHINXOPTS= > +SPHINXBUILD = sphinx-build > +PAPER = > +BUILDDIR = _build > + > +# Internal variables. > +PAPEROPT_a4 = -D latex_paper_size=a4 > +PAPEROPT_letter = -D latex_paper_size=letter > +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) > . > +# the i18n builder cannot share the environment and doctrees with the others > +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . > + > +.PHONY: all > all: drm-intel.html dim.html drm-misc.html > > %.svg: %.dot > @@ -41,7 +55,50 @@ mancheck: > > check: shellcheck mancheck all > > +.PHONY: clean > clean: > - rm -f drm-intel.html drm-intel-flow.svg drm-misc-commit-flow.svg > dim.html drm-misc.html > + rm -rf drm-intel.html drm-intel-flow.svg drm-misc-commit-flow.svg > dim.html drm-misc.html $(BUILDDIR) > + > +.PHONY: help > +help: > + @echo "Please use \`make ' where is one of" > + @echo " html to make standalone HTML files" > + @echo " dirhtmlto make HTML files named index.html in directories" > + @echo " singlehtml to make a single large HTML file" > + @echo " linkcheck to check all external links for integrity" > + @echo " doctestto run all doctests embedded in the documentation > (if enabled)" > + > +# FIXME: This works for the first build, but not for updates. Look into using > +# Sphinx extensions for both the graphviz and wavedrom parts. > +html dirhtml singlehtml linkcheck doctest: drm-intel-flow.svg > drm-misc-commit-flow.svg > + > +.PHONY: html > +html: > + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html > + @echo > + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." > + > +.PHONY: dirhtml > +dirhtml: > + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml > + @echo > + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." > + > +.PHONY: singlehtml > +singlehtml: > + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml > + @echo > + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." > + > +.PHONY: linkcheck > +linkcheck: > + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck > + @echo > + @echo "Link check complete; look for any errors in the above output " \ > + "or in $(BUILDDIR)/linkcheck/output.txt." > > -.PHONY: all clean > +.PHONY: doctest > +doctest: > + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest > + @echo "Testing of doctests in the sources finished, look at the " \ > + "results in $(BUILDDIR)/doctest/output.txt." > diff --git a/conf.py b/conf.py > new file mode 100644 > index ..385c2aa8ff66 > --- /dev/null > +++ b/conf.py > @@ -0,0 +1,236 @@ > +# -*- coding: utf-8 -*- > +# > +# DRM Maintainer Tools documentation build configuration file, created by > +# sphinx-quickstart on Wed Aug 9 17:57:16 2017. > +# > +# This file is execfile()d with the current directory set to its > +# containing dir. > +# > +# Note that not all possible configuration values are present in this > +# autogenerated file. > +# > +# All configuration values have a default; values that are commented out > +# serve to show the default. > + > +# If extensions (or modules to document with aut
