DOCS: Update notebooks and add user-guide

docs/conf.py

@@ -20,7 +20,7 @@
 import sphinx_bootstrap_theme
 
 
-sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath("../"))
 
 import pointpats
 
@@ -33,17 +33,18 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [#'sphinx_gallery.gen_gallery',
-              'sphinx.ext.autodoc',
-              'sphinx.ext.autosummary',
-              'sphinx.ext.viewcode',
-              'sphinxcontrib.bibtex',
-              'sphinx.ext.mathjax',
-              'sphinx.ext.doctest',
-              'sphinx.ext.intersphinx',
-              'numpydoc',
-              'matplotlib.sphinxext.plot_directive']
-
+extensions = [  #'sphinx_gallery.gen_gallery',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",
+    "sphinxcontrib.bibtex",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "numpydoc",
+    "matplotlib.sphinxext.plot_directive",
+    "nbsphinx",
+]
 
 
 # sphinx_gallery_conf = {
@@ -56,21 +57,21 @@
 
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+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'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = 'pointpats'
-copyright = '2018-, pysal developers'
-author = 'pysal developers'
+project = "pointpats"
+copyright = "2018-, pysal developers"
+author = "pysal developers"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -90,31 +91,31 @@
 # 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', 'tests/*']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "tests/*"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-bibtex_bibfiles = ['_static/references.bib']
+bibtex_bibfiles = ["_static/references.bib"]
 
 # -- 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'
-html_theme = 'bootstrap'
+html_theme = "bootstrap"
 html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 html_title = "%s v%s Manual" % (project, version)
 
 # (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).
 # Path should be relative to the ``_static`` files directory.
-#html_logo = "_static/images/CGS_logo.jpg"
-#html_logo = "_static/images/CGS_logo_green.png"
-#html_logo = "_static/images/pysal_logo_small.jpg"
+# html_logo = "_static/images/CGS_logo.jpg"
+# html_logo = "_static/images/CGS_logo_green.png"
+# html_logo = "_static/images/pysal_logo_small.jpg"
 html_favicon = "_static/images/pysal_favicon.ico"
 
 
@@ -123,80 +124,66 @@
 # documentation.
 #
 html_theme_options = {
-
     # Navigation bar title. (Default: ``project`` value)
-    'navbar_title': "pointpats",
-
+    "navbar_title": "pointpats",
     # Render the next and previous page links in navbar. (Default: true)
-    'navbar_sidebarrel': False,
-
+    "navbar_sidebarrel": False,
     # Render the current pages TOC in the navbar. (Default: true)
     #'navbar_pagenav': True,
     #'navbar_pagenav': False,
-
     # No sidebar
-    'nosidebar': True,
-
+    "nosidebar": True,
     # Tab name for the current pages TOC. (Default: "Page")
     #'navbar_pagenav_name': "Page",
-
     # Global TOC depth for "site" navbar tab. (Default: 1)
     # Switching to -1 shows all levels.
-    'globaltoc_depth': 2,
-
+    "globaltoc_depth": 2,
     # Include hidden TOCs in Site navbar?
     #
     # Note: If this is "false", you cannot have mixed ``:hidden:`` and
     # non-hidden ``toctree`` directives in the same page, or else the build
     # will break.
     #
     # Values: "true" (default) or "false"
-    'globaltoc_includehidden': "true",
-
+    "globaltoc_includehidden": "true",
     # HTML navbar class (Default: "navbar") to attach to <div> element.
     # For black navbar, do "navbar navbar-inverse"
     #'navbar_class': "navbar navbar-inverse",
-
     # Fix navigation bar to top of page?
     # Values: "true" (default) or "false"
-    'navbar_fixed_top': "true",
-
-
+    "navbar_fixed_top": "true",
     # Location of link to source.
     # Options are "nav" (default), "footer" or anything else to exclude.
-    'source_link_position': 'footer',
-
+    "source_link_position": "footer",
     # Bootswatch (http://bootswatch.com/) theme.
     #
     # Options are nothing (default) or the name of a valid theme
     # such as "amelia" or "cosmo", "yeti", "flatly".
-    'bootswatch_theme': "yeti",
-
+    "bootswatch_theme": "yeti",
     # Choose Bootstrap version.
     # Values: "3" (default) or "2" (in quotes)
-    'bootstrap_version': "3",
-
-    'navbar_links': [
-                     ("Installation", "installation"),
-                     ("API", "api"),
-                     ("References", "references"),
-                     ],
-
+    "bootstrap_version": "3",
+    "navbar_links": [
+        ("Installation", "installation"),
+        ("User Guide", "user-guide/intro"),
+        ("API", "api"),
+        ("References", "references"),
+    ],
 }
 
 # 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']
+html_static_path = ["_static"]
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+# html_sidebars = {}
 # html_sidebars = {'sidebar': ['localtoc.html', 'sourcelink.html', 'searchbox.html']}
 
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'pointpatsdoc'
+htmlhelp_basename = "pointpatsdoc"
 
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -205,15 +192,12 @@
     # 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',
@@ -223,19 +207,21 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'pointpats.tex', u'pointpats Documentation',
-     u'pysal developers', 'manual'),
+    (
+        master_doc,
+        "pointpats.tex",
+        "pointpats Documentation",
+        "pysal developers",
+        "manual",
+    ),
 ]
 
 
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'pointpats', u'pointpats Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "pointpats", "pointpats Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------
@@ -244,9 +230,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'pointpats', u'pointpats Documentation',
-     author, 'pointpats', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "pointpats",
+        "pointpats Documentation",
+        author,
+        "pointpats",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
 
 # -----------------------------------------------------------------------------
@@ -270,16 +262,18 @@
 
 # automatically document class members
 autodoc_default_options = {
-    'members': True,
-    'undoc-members': True,
-    'inherited-members': True
+    "members": True,
+    "undoc-members": True,
+    "inherited-members": True,
 }
 # display the source code for Plot directive
 plot_include_source = True
 
+
 def setup(app):
     app.add_css_file("pysal-styles.css")
 
+
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"python": ('https://docs.python.org/3', None),
                        'numpy': ('https://numpy.org/doc/stable', None),
@@ -291,4 +285,36 @@ def setup(app):
                        'statsmodels':("https://www.statsmodels.org/stable/", None),
                        }
 
+# List of arguments to be passed to the kernel that executes the notebooks:
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'svg', 'pdf'}",
+    "--InlineBackend.rc={'figure.dpi': 96}",
+]
+
+mathjax3_config = {
+    "TeX": {"equationNumbers": {"autoNumber": "AMS", "useLabelIds": True}},
+}
+
+# This is processed by Jinja2 and inserted after each notebook
+nbsphinx_epilog = r"""
+.. raw:: latex
+
+    \nbsphinxstopnotebook{\scriptsize\noindent\strut
+    \textcolor{gray}{\dotfill\ \sphinxcode{\sphinxupquote{\strut
+    {{ env.doc2path(env.docname, base='doc') | escape_latex }}}} ends here.}}
+"""
 
+# List of arguments to be passed to the kernel that executes the notebooks:
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'svg', 'pdf'}",
+    "--InlineBackend.rc={'figure.dpi': 96}",
+]
+
+# --- nbsphinx execution policy ---------------------------------------------
+nbsphinx_execute = "always"
+nbsphinx_timeout = 600
+# nbsphinx_allow_errors = True   # optional
+
+mathjax3_config = {
+    "TeX": {"equationNumbers": {"autoNumber": "AMS", "useLabelIds": True}},
+}