On Thu, 10 Aug 2017, Rodrigo Vivi <rodrigo.vivi@xxxxxxxxx> wrote: > On Wed, Aug 9, 2017 at 2:08 PM, Jani Nikula <jani.nikula@xxxxxxxxx> 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 <jani.nikula@xxxxxxxxx> >> --- >> .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..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 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, Jani Nikula, Daniel Vetter, and others' >> +author = u'Jani Nikula, Daniel Vetter' >> + >> +# 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 = 'alabaster' >> + >> +# 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@xxxxxxxxxxxxxxxxxxxxx >> https://lists.freedesktop.org/mailman/listinfo/intel-gfx -- Jani Nikula, Intel Open Source Technology Center _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/intel-gfx
