Doc tweaks

doc/conf.py

@@ -43,8 +43,10 @@
     'nbsphinx',
 ]
 
-# Override kernel name to allow running with Python 2 on Travis-CI
-nbsphinx_kernel_name = 'python'
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'svg', 'pdf'}",
+    "--InlineBackend.rc={'figure.dpi': 96}",
+]
 
 autoclass_content = 'init'
 autodoc_member_order = 'bysource'
@@ -73,7 +75,8 @@
 plot_include_source = True
 plot_html_show_source_link = False
 plot_html_show_formats = False
-plot_pre_code = ""
+plot_pre_code = ''
+plot_formats = ['svg', 'pdf']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_template']
@@ -152,6 +155,48 @@
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+jinja_define = """
+{% set docname = env.doc2path(env.docname, base='doc') %}
+{% set latex_href = ''.join([
+    '\href{https://github.com/sfstoolbox/sfs-python/blob/',
+    env.config.release,
+    '/',
+    docname | escape_latex,
+    '}{\sphinxcode{\sphinxupquote{',
+    docname | escape_latex,
+    '}}}',
+]) %}
+"""
+
+nbsphinx_prolog = jinja_define + r"""
+.. only:: html
+
+    .. role:: raw-html(raw)
+        :format: html
+
+    .. nbinfo::
+
+        This page was generated from `{{ docname }}`__.
+        Interactive online version:
+        :raw-html:`<a href="https://mybinder.org/v2/gh/sfstoolbox/sfs-python/{{ env.config.release }}?filepath={{ docname }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a>`
+
+    __ https://github.com/sfstoolbox/sfs-python/blob/
+        {{ env.config.release }}/{{ docname }}
+
+.. raw:: latex
+
+    \nbsphinxstartnotebook{\scriptsize\noindent\strut
+    \textcolor{gray}{The following section was generated from {{ latex_href }}
+    \dotfill}}
+"""
+
+nbsphinx_epilog = jinja_define + r"""
+.. raw:: latex
+
+    \nbsphinxstopnotebook{\scriptsize\noindent\strut
+    \textcolor{gray}{\dotfill\ {{ latex_href }} ends here.}}
+"""
+
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -225,6 +270,7 @@ def setup(app):
 
 # If true, links to the reST sources are added to the pages.
 html_show_sourcelink = True
+html_sourcelink_suffix = ''
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #html_show_sphinx = True
@@ -243,20 +289,32 @@ def setup(app):
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'SFS'
 
+html_scaled_image_link = False
 
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-'papersize': 'a4paper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-
-'printindex': '',
+    'papersize': 'a4paper',
+    'printindex': '',
+    'sphinxsetup': r"""
+        VerbatimColor={HTML}{F5F5F5},
+        VerbatimBorderColor={HTML}{E0E0E0},
+        noteBorderColor={HTML}{E0E0E0},
+        noteborder=1.5pt,
+        warningBorderColor={HTML}{E0E0E0},
+        warningborder=1.5pt,
+        warningBgColor={HTML}{FBFBFB},
+    """,
+    'preamble': r"""
+\usepackage[sc,osf]{mathpazo}
+\linespread{1.05}  % see http://www.tug.dk/FontCatalogue/urwpalladio/
+\renewcommand{\sfdefault}{pplj}  % Palatino instead of sans serif
+\IfFileExists{zlmtt.sty}{
+    \usepackage[light,scaled=1.05]{zlmtt}  % light typewriter font from lmodern
+}{
+    \renewcommand{\ttdefault}{lmtt}  % typewriter font from lmodern
+}
+""",
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/examples/ipython_kernel_config.py

@@ -0,0 +1,4 @@
+# See https://nbviewer.jupyter.org/github/mgeier/python-audio/blob/master/plotting/matplotlib-inline-defaults.ipynb
+
+c.InlineBackend.figure_formats = {'svg'}
+c.InlineBackend.rc = {'figure.dpi': 96}

doc/readthedocs-environment.yml

@@ -1,7 +1,7 @@
 channels:
   - conda-forge
 dependencies:
-  - python==3.5
+  - python>=3
   - sphinx>=1.3.6
   - sphinx_rtd_theme
   - sphinxcontrib-bibtex

readthedocs.yml

@@ -1,4 +1,4 @@
 conda:
     file: doc/readthedocs-environment.yml
 python:
-    setup_py_install: true
+    pip_install: true