Re: [Intel-gfx] [maintainer-tools PATCH 4/5] doc: build documentation using Sphinx

[Jani Nikula]

On Thu, 10 Aug 2017, Rodrigo Vivi  wrote:
> On Wed, Aug 9, 2017 at 2:08 PM, 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.
>
> the one that posts to 01.org or do we have more places pointing here?

I know of no others, but that doesn't prove anything! ;)

>
>>
>> Once we're fully converted to Sphinx, we can 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.
>
> when we know we are fully converted?

Perhaps we can move forward with more sphinxification once 01.org has
been converted. That already builds the kernel Sphinx docs, so shouldn't
be a big deal to switch to 'make html' and copy the results over from
_build/html.

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 ..2e7acb8e76ca
>> --- /dev/null
>> +++ b/conf.py
>> @@ -0,0 +1,236 @@
>> +# -*- coding: utf-8 -*-
>> +#
>> +# DRM Maintainer 

Re: [Intel-gfx] [maintainer-tools PATCH 4/5] doc: build documentation using Sphinx

[Rodrigo Vivi]

On Wed, Aug 9, 2017 at 2:08 PM, 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.

the one that posts to 01.org or do we have more places pointing here?

>
> Once we're fully converted to Sphinx, we can 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.

when we know we are fully converted?

>
> 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 ..2e7acb8e76ca
> --- /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 autodoc) are in another 
> 

[Intel-gfx] [maintainer-tools PATCH 4/5] doc: build documentation using Sphinx

[Jani Nikula]

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 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.

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 ..2e7acb8e76ca
--- /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 autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration 
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module