diff --git a/doc/conf.py b/doc/conf.py index 59904e1b..e56bc541 100644 --- a/doc/conf.py +++ b/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:`Binder badge` + + __ 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 diff --git a/doc/examples/ipython_kernel_config.py b/doc/examples/ipython_kernel_config.py new file mode 100644 index 00000000..c1fbebf2 --- /dev/null +++ b/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} diff --git a/doc/readthedocs-environment.yml b/doc/readthedocs-environment.yml index 7d346228..d5ff0570 100644 --- a/doc/readthedocs-environment.yml +++ b/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 diff --git a/readthedocs.yml b/readthedocs.yml index 03d06047..65bb0f41 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -1,4 +1,4 @@ conda: file: doc/readthedocs-environment.yml python: - setup_py_install: true + pip_install: true