[Intel-gfx] [maintainer-tools PATCH v2 4/4] doc: build documentation using Sphinx
Jani Nikula
jani.nikula at intel.com
Fri Aug 11 05:30:57 UTC 2017
On Thu, 10 Aug 2017, Rodrigo Vivi <rodrigo.vivi at gmail.com> 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 <rodrigo.vivi at intel.com>
Thanks Rodrigo and Sean for the acks/reviews, pushed.
BR,
Jani.
>
>>
>> Signed-off-by: Jani Nikula <jani.nikula at intel.com>
>> ---
>> .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 <target>' where <target> is one of"
>> + @echo " html to make standalone HTML files"
>> + @echo " dirhtml to 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 " doctest to 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 000000000000..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 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.
>> +# 1.3 has builtin sphinx_rtd_theme
>> +needs_sphinx = '1.3'
>> +
>> +# Add any Sphinx extension module names here, as strings. They can be
>> +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
>> +# ones.
>> +extensions = []
>> +
>> +# Add any paths that contain templates here, relative to this directory.
>> +templates_path = ['_templates']
>> +
>> +# The suffix(es) of source filenames.
>> +# You can specify multiple suffix as a list of string:
>> +#
>> +# source_suffix = ['.rst', '.md']
>> +source_suffix = '.rst'
>> +
>> +# The encoding of source files.
>> +#
>> +# source_encoding = 'utf-8-sig'
>> +
>> +# The master toctree document.
>> +master_doc = 'index'
>> +
>> +# General information about the project.
>> +project = u'DRM Maintainer Tools'
>> +copyright = u'2012-2017, Intel Corporation'
>> +author = u'Jani Nikula, Daniel Vetter, and others'
>> +
>> +# The version info for the project you're documenting, acts as replacement for
>> +# |version| and |release|, also used in various other places throughout the
>> +# built documents.
>> +#
>> +# The short X.Y version.
>> +version = u'1.0'
>> +# The full version, including alpha/beta/rc tags.
>> +release = u'1.0'
>> +
>> +# The language for content autogenerated by Sphinx. Refer to documentation
>> +# for a list of supported languages.
>> +#
>> +# This is also used if you do content translation via gettext catalogs.
>> +# Usually you set "language" from the command line for these cases.
>> +language = None
>> +
>> +# There are two options for replacing |today|: either, you set today to some
>> +# non-false value, then it is used:
>> +#
>> +# today = ''
>> +#
>> +# Else, today_fmt is used as the format for a strftime call.
>> +#
>> +# today_fmt = '%B %d, %Y'
>> +
>> +# List of patterns, relative to source directory, that match files and
>> +# directories to ignore when looking for source files.
>> +# This patterns also effect to html_static_path and html_extra_path
>> +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
>> +
>> +# The reST default role (used for this markup: `text`) to use for all
>> +# documents.
>> +#
>> +# default_role = None
>> +
>> +# If true, '()' will be appended to :func: etc. cross-reference text.
>> +#
>> +# add_function_parentheses = True
>> +
>> +# If true, the current module name will be prepended to all description
>> +# unit titles (such as .. function::).
>> +#
>> +# add_module_names = True
>> +
>> +# If true, sectionauthor and moduleauthor directives will be shown in the
>> +# output. They are ignored by default.
>> +#
>> +# show_authors = False
>> +
>> +# The name of the Pygments (syntax highlighting) style to use.
>> +pygments_style = 'sphinx'
>> +
>> +# A list of ignored prefixes for module index sorting.
>> +# modindex_common_prefix = []
>> +
>> +# If true, keep warnings as "system message" paragraphs in the built documents.
>> +# keep_warnings = False
>> +
>> +# If true, `todo` and `todoList` produce output, else they produce nothing.
>> +todo_include_todos = False
>> +
>> +
>> +# -- Options for HTML output ----------------------------------------------
>> +
>> +# The theme to use for HTML and HTML Help pages. See the documentation for
>> +# a list of builtin themes.
>> +#
>> +html_theme = 'sphinx_rtd_theme'
>> +
>> +# Theme options are theme-specific and customize the look and feel of a theme
>> +# further. For a list of options available for each theme, see the
>> +# documentation.
>> +#
>> +# html_theme_options = {}
>> +
>> +# Add any paths that contain custom themes here, relative to this directory.
>> +# html_theme_path = []
>> +
>> +# The name for this set of Sphinx documents.
>> +# "<project> v<release> documentation" by default.
>> +#
>> +# html_title = u'DRM Maintainer Tools v1.0'
>> +
>> +# A shorter title for the navigation bar. Default is the same as html_title.
>> +#
>> +# html_short_title = None
>> +
>> +# The name of an image file (relative to this directory) to place at the top
>> +# of the sidebar.
>> +#
>> +# html_logo = None
>> +
>> +# The name of an image file (relative to this directory) to use as a favicon of
>> +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
>> +# pixels large.
>> +#
>> +# html_favicon = None
>> +
>> +# Add any paths that contain custom static files (such as style sheets) here,
>> +# relative to this directory. They are copied after the builtin static files,
>> +# so a file named "default.css" will overwrite the builtin "default.css".
>> +html_static_path = ['_static']
>> +
>> +# Add any extra paths that contain custom files (such as robots.txt or
>> +# .htaccess) here, relative to this directory. These files are copied
>> +# directly to the root of the documentation.
>> +#
>> +# html_extra_path = []
>> +
>> +# If not None, a 'Last updated on:' timestamp is inserted at every page
>> +# bottom, using the given strftime format.
>> +# The empty string is equivalent to '%b %d, %Y'.
>> +#
>> +# html_last_updated_fmt = None
>> +
>> +# If true, SmartyPants will be used to convert quotes and dashes to
>> +# typographically correct entities.
>> +#
>> +# html_use_smartypants = True
>> +
>> +# Custom sidebar templates, maps document names to template names.
>> +#
>> +# html_sidebars = {}
>> +
>> +# Additional templates that should be rendered to pages, maps page names to
>> +# template names.
>> +#
>> +# html_additional_pages = {}
>> +
>> +# If false, no module index is generated.
>> +#
>> +# html_domain_indices = True
>> +
>> +# If false, no index is generated.
>> +#
>> +# html_use_index = True
>> +
>> +# If true, the index is split into individual pages for each letter.
>> +#
>> +# html_split_index = False
>> +
>> +# If true, links to the reST sources are added to the pages.
>> +#
>> +# html_show_sourcelink = True
>> +
>> +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
>> +#
>> +# html_show_sphinx = True
>> +
>> +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
>> +#
>> +# html_show_copyright = True
>> +
>> +# If true, an OpenSearch description file will be output, and all pages will
>> +# contain a <link> tag referring to it. The value of this option must be the
>> +# base URL from which the finished HTML is served.
>> +#
>> +# html_use_opensearch = ''
>> +
>> +# This is the file name suffix for HTML files (e.g. ".xhtml").
>> +# html_file_suffix = None
>> +
>> +# Language to be used for generating the HTML full-text search index.
>> +# Sphinx supports the following languages:
>> +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
>> +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
>> +#
>> +# html_search_language = 'en'
>> +
>> +# A dictionary with options for the search language support, empty by default.
>> +# 'ja' uses this config value.
>> +# 'zh' user can custom change `jieba` dictionary path.
>> +#
>> +# html_search_options = {'type': 'default'}
>> +
>> +# The name of a javascript file (relative to the configuration directory) that
>> +# implements a search results scorer. If empty, the default will be used.
>> +#
>> +# html_search_scorer = 'scorer.js'
>> +
>> +# Output file base name for HTML help builder.
>> +htmlhelp_basename = 'DRMMaintainerToolsdoc'
>> diff --git a/index.rst b/index.rst
>> new file mode 100644
>> index 000000000000..d8b6d4897c45
>> --- /dev/null
>> +++ b/index.rst
>> @@ -0,0 +1,17 @@
>> +DRM Maintainer Tools
>> +====================
>> +
>> +Contents:
>> +
>> +.. toctree::
>> + :maxdepth: 2
>> +
>> + drm-misc
>> + drm-intel
>> + dim
>> +
>> +Indices and tables
>> +==================
>> +
>> +* :ref:`genindex`
>> +* :ref:`search`
>> --
>> 2.11.0
>>
>> _______________________________________________
>> Intel-gfx mailing list
>> Intel-gfx at lists.freedesktop.org
>> https://lists.freedesktop.org/mailman/listinfo/intel-gfx
--
Jani Nikula, Intel Open Source Technology Center
More information about the Intel-gfx
mailing list