12 files changed, 172 insertions, 346 deletions

diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt
deleted file mode 100644
index c5e75e0..0000000
--- a/doc/_static/conf.py.txt
+++ /dev/null
@@ -1,346 +0,0 @@
-# test documentation build configuration file, created by
-# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
-#
-# This file is executed through importlib.import_module 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.
-root_doc = 'index'
-
-# General information about the project.
-project = 'test'
-copyright = '2016, test'
-author = 'test'
-
-# 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 = 'test'
-# The full version, including alpha/beta/rc tags.
-release = 'test'
-
-# 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.
-# These patterns also affect 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 = 'test vtest'
-
-# 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
-
-# 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 = 'testdoc'
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (root_doc, 'test.tex', 'test Documentation',
-     'test', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#
-# latex_logo = None
-
-# If true, show page references after internal links.
-#
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#
-# latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#
-# latex_appendices = []
-
-# If false, no module index is generated.
-#
-# latex_domain_indices = True
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (root_doc, 'test', 'test Documentation',
-     [author], 1)
-]
-
-# If true, show URL addresses after external links.
-#
-# man_show_urls = False
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (root_doc, 'test', 'test Documentation',
-     author, 'test', 'One line description of project.',
-     'Miscellaneous'),
-]
-
-# Documents to append as an appendix to all manuals.
-#
-# texinfo_appendices = []
-
-# If false, no module index is generated.
-#
-# texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#
-# texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#
-# texinfo_no_detailmenu = False
-
-# If false, do not generate in manual @ref nodes.
-#
-# texinfo_cross_references = False
-
-# -- A random example -----------------------------------------------------
-
-import sys, os
-sys.path.insert(0, os.path.abspath('.'))
-exclude_patterns = ['zzz']
-
-numfig = True
-#language = 'ja'
-
-extensions.append('sphinx.ext.todo')
-extensions.append('sphinx.ext.autodoc')
-#extensions.append('sphinx.ext.autosummary')
-extensions.append('sphinx.ext.intersphinx')
-extensions.append('sphinx.ext.mathjax')
-extensions.append('sphinx.ext.viewcode')
-extensions.append('sphinx.ext.graphviz')
-
-
-autosummary_generate = True
-html_theme = 'default'
-#source_suffix = ['.rst', '.txt']
diff --git a/doc/_static/diagrams/sphinx_build_flow.dot b/doc/_static/diagrams/sphinx_build_flow.dot
new file mode 100644
index 0000000..0e736f5
--- /dev/null
+++ b/doc/_static/diagrams/sphinx_build_flow.dot
@@ -0,0 +1,47 @@
+// UML for the standard Sphinx build workflow
+
+digraph build {
+    graph [
+        rankdir=LR
+    ];
+    node [
+        shape=rect
+        style=rounded
+    ];
+
+    "Sphinx" [
+        shape=record
+        label = "Sphinx | <init> __init__ | <build> build"
+    ];
+    "Sphinx":init -> "Builder.init";
+    "Sphinx":build -> "Builder.build_all";
+    "Sphinx":build -> "Builder.build_specific";
+    "Builder.build_update" [
+        shape=record
+        label = "<p1> Builder.build_update | Builder.get_outdated_docs"
+    ];
+    "Sphinx":build -> "Builder.build_update":p1 ;
+
+    "Builder.build_all" -> "Builder.build";
+    "Builder.build_specific" -> "Builder.build";
+    "Builder.build_update":p1 -> "Builder.build";
+
+    "Builder.build" -> "Builder.read";
+    "Builder.write" [
+        shape=record
+        label = "<p1> Builder.write | Builder._write_serial | Builder._write_parallel"
+    ];
+    "Builder.build" -> "Builder.write";
+    "Builder.build" -> "Builder.finish";
+
+    "Builder.read" -> "Builder.read_doc";
+    "Builder.read_doc" -> "Builder.write_doctree";
+
+    "Builder.write":p1 -> "Builder.prepare_writing";
+    "Builder.write":p1 -> "Builder.copy_assets";
+    "Builder.write":p1 -> "Builder.write_doc";
+
+    "Builder.write_doc" -> "Builder.get_relative_uri";
+
+    "Builder.get_relative_uri" -> "Builder.get_target_uri";
+}
diff --git a/doc/_static/diagrams/sphinx_core_events_flow.dot b/doc/_static/diagrams/sphinx_core_events_flow.dot
new file mode 100644
index 0000000..1499e6b
--- /dev/null
+++ b/doc/_static/diagrams/sphinx_core_events_flow.dot
@@ -0,0 +1,125 @@
+// A flow graph of the Sphinx build process, highlighting event callbacks
+
+digraph events {
+    graph [
+        rankdir=TB
+    ];
+    node [
+        shape=rect
+        style=rounded
+    ];
+    "Sphinx" [
+        shape=record
+        label = "<init> Sphinx.__init__() | <build> Sphinx.build()"
+    ];
+
+    // During initialization
+    "config-inited"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Sphinx":init -> "config-inited";
+    "builder-inited"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Sphinx":init -> "builder-inited";
+
+    // During build
+    "Builder" [label = "Builder.build()"]
+    "Sphinx":build -> "Builder";
+    "Builder.build" [
+        shape=record
+        label = "
+            <before_read> before read |
+            <read> read |
+            <after_read> after read |
+            <write> write |
+            <finalize> finalize"
+    ];
+    "Builder" -> "Builder.build";
+
+    "env-get-outdated"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":before_read -> "env-get-outdated";
+    remove_each_doc [shape="ellipse", label="for removed"];
+    "Builder.build":before_read -> "remove_each_doc";
+    "env-purge-doc"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "remove_each_doc" -> "env-purge-doc";
+    "env-before-read-docs"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":before_read -> "env-before-read-docs";
+
+    // during read phase
+    "Builder.read" [label = "Builder.read()"]
+    "Builder.build":read -> "Builder.read";
+    read_each_doc [shape="ellipse", label="for added | changed"];
+    "Builder.read" -> "read_each_doc";
+    merge_each_process [
+    shape="ellipse", label="for each process\n(parallel only)"
+    ];
+    "Builder.read" -> merge_each_process;
+    "env-updated"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.read" -> "env-updated"
+
+    // during read phase, for each document/process
+    "env-purge-doc"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "read_each_doc" -> "env-purge-doc";
+    "source-read"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "read_each_doc" -> "source-read";
+    "Include" [label="Include\ndirective"]
+    "read_each_doc" -> "Include";
+    "include-read"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Include" -> "include-read";
+    "ObjectDescription" [label="ObjectDescription\ndirective"]
+    "read_each_doc" -> "ObjectDescription";
+    "object-description-transform"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "ObjectDescription" -> "object-description-transform";
+    "doctree-read"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "read_each_doc" -> "doctree-read";
+    "env-merge-info"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "merge_each_process" -> "env-merge-info";
+
+    // after read phase
+    "env-get-updated"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":after_read -> "env-get-updated";
+    if_read_changes [shape="diamond", label="if changed\ndocuments"];
+    "Builder.build":after_read -> if_read_changes;
+    if_read_changes -> "cache the\nBuild.Environment";
+    "env-check-consistency"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    if_read_changes -> "env-check-consistency";
+
+    // during write phase
+    "write-started"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":write -> "write-started";
+    "Builder.write" [label = "Builder.write()"]
+    "Builder.build":write -> "Builder.write";
+    write_each_doc [shape="ellipse", label="for updated"];
+    "Builder.write" -> write_each_doc;
+    "ReferenceResolver" [
+    label="ReferenceResolver\nPost-transform"
+    ]
+    write_each_doc -> "ReferenceResolver";
+    "missing-reference"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    ReferenceResolver -> "missing-reference";
+    "warn-missing-reference"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    ReferenceResolver -> "warn-missing-reference";
+    "HyperlinkCollector" [
+    label="HyperlinkCollector\nPost-transform"
+    ]
+    write_each_doc -> "HyperlinkCollector";
+    "linkcheck-process-uri"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    HyperlinkCollector -> "linkcheck-process-uri";
+    "doctree-resolved"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    write_each_doc -> "doctree-resolved";
+    "html-page-context"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    write_each_doc -> "html-page-context";
+
+    // html only
+    "html-collect-pages"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":finalize -> "html-collect-pages";
+
+    // finalize build
+    "build-finished"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":finalize -> "build-finished";
+
+    // constrain layout ordering
+    {rank=same "config-inited" "builder-inited"};
+    {rank=same; "env-get-outdated" "env-before-read-docs" "env-get-updated"};
+    {rank=same; "env-purge-doc" "source-read" "doctree-read", "merge_each_process"};
+    {rank=same; "env-updated" "env-check-consistency"};
+    {rank=same; "env-merge-info" "write-started" "Builder.write"};
+    {rank=max; "build-finished"};
+}
diff --git a/doc/_static/jupyter-logo.png b/doc/_static/jupyter-logo.png
new file mode 100644
index 0000000..f50121c
--- /dev/null
+++ b/doc/_static/jupyter-logo.png
diff --git a/doc/_static/linux-logo.png b/doc/_static/linux-logo.png
new file mode 100644
index 0000000..b707653
--- /dev/null
+++ b/doc/_static/linux-logo.png
diff --git a/doc/_static/more.png b/doc/_static/more.png
deleted file mode 100644
index 97553a8..0000000
--- a/doc/_static/more.png
+++ /dev/null
diff --git a/doc/_static/python-logo.png b/doc/_static/python-logo.png
new file mode 100644
index 0000000..34e6fec
--- /dev/null
+++ b/doc/_static/python-logo.png
diff --git a/doc/_static/tutorial/lumache-autosummary.png b/doc/_static/tutorial/lumache-autosummary.png
index ed54ea3..f3d98a5 100644
--- a/doc/_static/tutorial/lumache-autosummary.png
+++ b/doc/_static/tutorial/lumache-autosummary.png
diff --git a/doc/_static/tutorial/lumache-first-light.png b/doc/_static/tutorial/lumache-first-light.png
index fbf4aec..9a604cd 100644
--- a/doc/_static/tutorial/lumache-first-light.png
+++ b/doc/_static/tutorial/lumache-first-light.png
diff --git a/doc/_static/tutorial/lumache-furo.png b/doc/_static/tutorial/lumache-furo.png
index c7aaee7..e3a1367 100644
--- a/doc/_static/tutorial/lumache-furo.png
+++ b/doc/_static/tutorial/lumache-furo.png
diff --git a/doc/_static/tutorial/lumache-py-function-full.png b/doc/_static/tutorial/lumache-py-function-full.png
index d13b637..9991b52 100644
--- a/doc/_static/tutorial/lumache-py-function-full.png
+++ b/doc/_static/tutorial/lumache-py-function-full.png
diff --git a/doc/_static/tutorial/lumache-py-function.png b/doc/_static/tutorial/lumache-py-function.png
index 06129d5..bf18d85 100644
--- a/doc/_static/tutorial/lumache-py-function.png
+++ b/doc/_static/tutorial/lumache-py-function.png