##// END OF EJS Templates
Default backend is 'agg'. `None` is no matplotlib.
chebee7i -
Show More
@@ -44,22 +44,23 b' ipython_mplbackend:'
44 The string which specifies if the embedded Sphinx shell should import
44 The string which specifies if the embedded Sphinx shell should import
45 Matplotlib and set the backend. The value specifies a backend that is
45 Matplotlib and set the backend. The value specifies a backend that is
46 passed to `matplotlib.use()` before any lines in `ipython_execlines` are
46 passed to `matplotlib.use()` before any lines in `ipython_execlines` are
47 executed. If specified in conf.py as `None` or not specified in conf.py at
47 executed. If not specified in conf.py, then the default value of 'agg' is
48 all, then no call to `matplotlib.use()` is made. Then, matplotlib is loaded
48 used. To use the IPython directive without matplotlib as a dependency, set
49 only if specified in `ipython_execlines` or if the @savefig pseudo
49 the value to `None`. It may end up that matplotlib is still imported
50 decorator is used. In the latter case, matplotlib is imported and its
50 if the user specifies so in `ipython_execlines` or makes use of the
51 default backend is used.
51 @savefig pseudo decorator.
52 ipython_execlines:
52 ipython_execlines:
53 A list of strings to be exec'd for the embedded Sphinx shell. Typical
53 A list of strings to be exec'd in the embedded Sphinx shell. Typical
54 usage is to make certain packages always available. Set this to an empty
54 usage is to make certain packages always available. Set this to an empty
55 list if you wish to have no imports always available. If specified in
55 list if you wish to have no imports always available. If specified in
56 conf.py as `None` or not specified in conf.py at all, then the default
56 conf.py as `None`, then it has the effect of making no imports available.
57 value of ['import numpy as np', 'from pylab import *'] is used.
57 If omitted from conf.py altogether, then the default value of
58 ['import numpy as np', 'import matplotlib.pyplot as plt'] is used.
58
59
59 As an example, to use the IPython directive when `matplotlib` is not available,
60 As an example, to use the IPython directive when `matplotlib` is not available,
60 one sets the backend to `None`::
61 one sets the backend to `'none'`::
61
62
62 ipython_mplbacked = None
63 ipython_mplbacked = 'none'
63
64
64 An example usage of the directive is:
65 An example usage of the directive is:
65
66
@@ -73,7 +74,7 b' An example usage of the directive is:'
73
74
74 In [3]: print(y)
75 In [3]: print(y)
75
76
76 See http://matplotlib.org/sampledoc/ipython_directive.html for more additional
77 See http://matplotlib.org/sampledoc/ipython_directive.html for additional
77 documentation.
78 documentation.
78
79
79 ToDo
80 ToDo
@@ -517,8 +518,27 b' class EmbeddedSphinxShell(object):'
517 return ret, image_directive
518 return ret, image_directive
518
519
519 def ensure_pyplot(self):
520 def ensure_pyplot(self):
520 if self._pyplot_imported:
521 """
521 return
522 Ensures that pyplot has been imported into the embedded IPython shell.
523
524 Also, makes sure to set the backend appropriately if not set already.
525
526 """
527 # We are here if the @figure pseudo decorator was used. Thus, it's
528 # possible that we could be here even if python_mplbackend were set to
529 # `None`. That's also strange and perhaps worthy of raising an
530 # exception, but for now, we just set the backend to 'agg'.
531
532 if not self._pyplot_imported:
533 if 'matplotlib.backends' not in sys.modules:
534 # Then ipython_matplotlib was set to None but there was a
535 # call to the @figure decorator (and ipython_execlines did
536 # not set a backend).
537 #raise Exception("No backend was set, but @figure was used!")
538 import matplotlib
539 matplotlib.use('agg')
540
541 # Always import pyplot into embedded shell.
522 self.process_input_line('import matplotlib.pyplot as plt',
542 self.process_input_line('import matplotlib.pyplot as plt',
523 store_history=False)
543 store_history=False)
524 self._pyplot_imported = True
544 self._pyplot_imported = True
@@ -655,14 +675,6 b' class IPythonDirective(Directive):'
655 mplbackend = config.ipython_mplbackend
675 mplbackend = config.ipython_mplbackend
656 exec_lines = config.ipython_execlines
676 exec_lines = config.ipython_execlines
657
677
658 # Handle None uniformly, whether specified in conf.py as `None` or
659 # omitted entirely from conf.py.
660
661 if mplbackend is None:
662 mplbackend = 'agg'
663 if exec_lines is None:
664 exec_lines = ['import numpy as np', 'from pylab import *']
665
666 return (savefig_dir, source_dir, rgxin, rgxout,
678 return (savefig_dir, source_dir, rgxin, rgxout,
667 promptin, promptout, mplbackend, exec_lines)
679 promptin, promptout, mplbackend, exec_lines)
668
680
@@ -672,6 +684,10 b' class IPythonDirective(Directive):'
672 promptout, mplbackend, exec_lines) = self.get_config_options()
684 promptout, mplbackend, exec_lines) = self.get_config_options()
673
685
674 if self.shell is None:
686 if self.shell is None:
687 # We will be here many times. However, when the
688 # EmbeddedSphinxShell is created, its interactive shell member
689 # is the same for each instance.
690
675 if mplbackend:
691 if mplbackend:
676 import matplotlib
692 import matplotlib
677 # Repeated calls to use() will not hurt us since `mplbackend`
693 # Repeated calls to use() will not hurt us since `mplbackend`
@@ -764,7 +780,7 b' class IPythonDirective(Directive):'
764 # cleanup
780 # cleanup
765 self.teardown()
781 self.teardown()
766
782
767 return []#, imgnode]
783 return []
768
784
769 # Enable as a proper Sphinx directive
785 # Enable as a proper Sphinx directive
770 def setup(app):
786 def setup(app):
@@ -778,8 +794,15 b' def setup(app):'
778 re.compile('Out\[(\d+)\]:\s?(.*)\s*'), 'env')
794 re.compile('Out\[(\d+)\]:\s?(.*)\s*'), 'env')
779 app.add_config_value('ipython_promptin', 'In [%d]:', 'env')
795 app.add_config_value('ipython_promptin', 'In [%d]:', 'env')
780 app.add_config_value('ipython_promptout', 'Out[%d]:', 'env')
796 app.add_config_value('ipython_promptout', 'Out[%d]:', 'env')
781 app.add_config_value('ipython_mplbackend', None, 'env')
797 # We could just let matplotlib pick whatever is specified as the default
782 app.add_config_value('ipython_execlines', None, 'env')
798 # backend in the matplotlibrc file, but this would cause issues if the
799 # backend didn't work in headless environments. For this reason, 'agg'
800 # is a good default backend choice.
801 app.add_config_value('ipython_mplbackend', 'agg', 'env')
802 # If the user sets this config value to `None`, then EmbeddedSphinxShell's
803 # __init__ method will treat it as [].
804 execlines = ['import numpy as np', 'import matplotlib.pyplot as plt']
805 app.add_config_value('ipython_execlines', execlines, 'env')
783
806
784 # Simple smoke test, needs to be converted to a proper automatic test.
807 # Simple smoke test, needs to be converted to a proper automatic test.
785 def test():
808 def test():
General Comments 0
You need to be logged in to leave comments. Login now