def generate_configuration(directory):
"""
Generates a Sphinx configuration in `directory`.
Parameters
----------
directory : str
Base directory to use
"""
# conf.py file for Sphinx
conf = osp.join(get_module_source_path("SMlib.utils.inspector"), "conf.py")
# Docstring layout page (in Jinja):
layout = osp.join(osp.join(CONFDIR_PATH, "templates"), "layout.html")
os.makedirs(osp.join(directory, "templates"))
os.makedirs(osp.join(directory, "static"))
shutil.copy(conf, directory)
shutil.copy(layout, osp.join(directory, "templates"))
open(osp.join(directory, "__init__.py"), "w").write("")
open(osp.join(directory, "static", "empty"), "w").write("")
def generate_configuration(directory):
"""
Generates a Sphinx configuration in `directory`.
Parameters
----------
directory : str
Base directory to use
"""
# conf.py file for Sphinx
conf = osp.join(get_module_source_path('SMlib.utils.inspector'),
'conf.py')
# Docstring layout page (in Jinja):
layout = osp.join(osp.join(CONFDIR_PATH, 'templates'), 'layout.html')
os.makedirs(osp.join(directory, 'templates'))
os.makedirs(osp.join(directory, 'static'))
shutil.copy(conf, directory)
shutil.copy(layout, osp.join(directory, 'templates'))
open(osp.join(directory, '__init__.py'), 'w').write('')
open(osp.join(directory, 'static', 'empty'), 'w').write('')
def __init__(self, parent=None, fname=None, wdir=None,
interact=False, debug=False, path=[], python_args='',
ipykernel=False, arguments='', stand_alone=None,
umd_enabled=True, umd_namelist=[], umd_verbose=True,
pythonstartup=None, pythonexecutable=None,
monitor_enabled=True, mpl_patch_enabled=True,
mpl_backend=None, ets_backend='qt4', qt_api=None, pyqt_api=0,
install_qt_inputhook=True, ignore_sip_setapi_errors=False,
merge_output_channels=False, colorize_sys_stderr=False,
autorefresh_timeout=3000, autorefresh_state=True,
light_background=True, menu_actions=None,
show_buttons_inside=True, show_elapsed_time=True):
assert qt_api in (None, 'pyqt', 'pyside')
self.namespacebrowser = None # namespace browser widget!
self.dialog_manager = DialogManager()
self.stand_alone = stand_alone # stand alone settings (None: plugin)
self.pythonstartup = pythonstartup
self.pythonexecutable = pythonexecutable
self.monitor_enabled = monitor_enabled
self.mpl_patch_enabled = mpl_patch_enabled
self.mpl_backend = mpl_backend
self.ets_backend = ets_backend
self.qt_api = qt_api
self.pyqt_api = pyqt_api
self.install_qt_inputhook = install_qt_inputhook
self.ignore_sip_setapi_errors = ignore_sip_setapi_errors
self.merge_output_channels = merge_output_channels
self.colorize_sys_stderr = colorize_sys_stderr
self.umd_enabled = umd_enabled
self.umd_namelist = umd_namelist
self.umd_verbose = umd_verbose
self.autorefresh_timeout = autorefresh_timeout
self.autorefresh_state = autorefresh_state
self.namespacebrowser_button = None
self.cwd_button = None
self.env_button = None
self.syspath_button = None
self.terminate_button = None
self.notification_thread = None
ExternalShellBase.__init__(self, parent=parent, fname=fname, wdir=wdir,
history_filename='.history.py',
light_background=light_background,
menu_actions=menu_actions,
show_buttons_inside=show_buttons_inside,
show_elapsed_time=show_elapsed_time)
if self.pythonexecutable is None:
self.pythonexecutable = get_python_executable()
self.python_args = None
if python_args:
assert isinstance(python_args, basestring)
self.python_args = python_args
assert isinstance(arguments, basestring)
self.arguments = arguments
self.connection_file = None
self.is_ipykernel = ipykernel
if self.is_ipykernel:
interact = False
# Running our custom startup script for IPython kernels:
# (see spyderlib/widgets/externalshell/start_ipython_kernel.py)
self.fname = get_module_source_path(
'SMlib.widgets.externalshell', 'start_ipython_kernel.py')
self.shell.set_externalshell(self)
self.toggle_globals_explorer(False)
self.interact_action.setChecked(interact)
self.debug_action.setChecked(debug)
self.introspection_socket = None
self.is_interpreter = fname is None
if self.is_interpreter:
self.terminate_button.hide()
# Additional python path list
self.path = path
self.shell.path = path
# -*- coding: utf-8 -*- # # Copyright © 2011 Pierre Raybaut # Licensed under the terms of the MIT License # (see spyderlib/__init__.py for details) """ spyderlib.utils.external ======================== External libraries needed for Spyder to work. Put here only untouched libraries, else put them in utils. """ import sys from SMlib.configs.baseconfig import get_module_source_path sys.path.insert(0, get_module_source_path(__name__))
def sphinxify(docstring, context, buildername='html'):
"""
Runs Sphinx on a docstring and outputs the processed documentation.
Parameters
----------
docstring : str
a ReST-formatted docstring
context : dict
Variables to be passed to the layout template to control how its
rendered (through the Sphinx variable *html_context*).
buildername: str
It can be either `html` or `text`.
Returns
-------
An Sphinx-processed string, in either HTML or plain text format, depending
on the value of `buildername`
"""
srcdir = mkdtemp()
srcdir = encoding.to_unicode_from_fs(srcdir)
base_name = osp.join(srcdir, 'docstring')
rst_name = base_name + '.rst'
if buildername == 'html':
suffix = '.html'
else:
suffix = '.txt'
output_name = base_name + suffix
# This is needed so users can type \\ on latex eqnarray envs inside raw
# docstrings
if context['right_sphinx_version'] and context['math_on']:
docstring = docstring.replace('\\\\', '\\\\\\\\')
# Add a class to several characters on the argspec. This way we can
# highlight them using css, in a similar way to what IPython does.
argspec = context['argspec']
for char in ['=', ',', '(', ')', '*', '**']:
argspec = argspec.replace(char,
'<span class="argspec-highlight">' + char + '</span>')
context['argspec'] = argspec
doc_file = codecs.open(rst_name, 'w', encoding='utf-8')
doc_file.write(docstring)
doc_file.close()
temp_confdir = False
if temp_confdir:
# TODO: This may be inefficient. Find a faster way to do it.
confdir = mkdtemp()
confdir = encoding.to_unicode_from_fs(confdir)
generate_configuration(confdir)
else:
confdir = osp.join(get_module_source_path('SMlib.utils.inspector'))
confoverrides = {'html_context': context}
doctreedir = osp.join(srcdir, 'doctrees')
sphinx_app = Sphinx(srcdir, confdir, srcdir, doctreedir, buildername,
confoverrides, status=None, warning=None,
freshenv=True, warningiserror=False, tags=None)
try:
sphinx_app.build(None, [rst_name])
except SystemMessage:
output = _("It was not possible to generate rich text help for this "
"object.</br>"
"Please see it in plain text.")
return warning(output)
# TODO: Investigate if this is necessary/important for us
if osp.exists(output_name):
output = codecs.open(output_name, 'r', encoding='utf-8').read()
output = output.replace('<pre>', '<pre class="literal-block">')
else:
output = _("It was not possible to generate rich text help for this "
"object.</br>"
"Please see it in plain text.")
return warning(output)
if temp_confdir:
shutil.rmtree(confdir, ignore_errors=True)
shutil.rmtree(srcdir, ignore_errors=True)
return output
import sphinx
from sphinx.application import Sphinx
# Local imports
from SMlib.configs.baseconfig import (_, get_module_data_path,
get_module_source_path)
from SMlib.utils import encoding
#-----------------------------------------------------------------------------
# Globals and constants
#-----------------------------------------------------------------------------
# Note: we do not use __file__ because it won't be working in the stand-alone
# version of Spyder (i.e. the py2exe or cx_Freeze build)
CONFDIR_PATH = get_module_source_path('SMlib.utils.inspector')
CSS_PATH = osp.join(CONFDIR_PATH, 'static', 'css')
JS_PATH = osp.join(CONFDIR_PATH, 'js')
# To let Debian packagers redefine the MathJax and JQuery locations so they can
# use their own packages for them. See Issue 1230, comment #7.
MATHJAX_PATH = get_module_data_path('SMlib',
relpath=osp.join('utils', 'inspector',
JS_PATH, 'mathjax'),
attr_name='MATHJAXPATH')
JQUERY_PATH = get_module_data_path('SMlib',
relpath=osp.join('utils', 'inspector',
JS_PATH),
attr_name='JQUERYPATH')
def __init__(self,
parent=None,
fname=None,
wdir=None,
interact=False,
debug=False,
path=[],
python_args='',
ipykernel=False,
arguments='',
stand_alone=None,
umd_enabled=True,
umd_namelist=[],
umd_verbose=True,
pythonstartup=None,
pythonexecutable=None,
monitor_enabled=True,
mpl_patch_enabled=True,
mpl_backend=None,
ets_backend='qt4',
qt_api=None,
pyqt_api=0,
install_qt_inputhook=True,
ignore_sip_setapi_errors=False,
merge_output_channels=False,
colorize_sys_stderr=False,
autorefresh_timeout=3000,
autorefresh_state=True,
light_background=True,
menu_actions=None,
show_buttons_inside=True,
show_elapsed_time=True):
assert qt_api in (None, 'pyqt', 'pyside')
self.namespacebrowser = None # namespace browser widget!
self.dialog_manager = DialogManager()
self.stand_alone = stand_alone # stand alone settings (None: plugin)
self.pythonstartup = pythonstartup
self.pythonexecutable = pythonexecutable
self.monitor_enabled = monitor_enabled
self.mpl_patch_enabled = mpl_patch_enabled
self.mpl_backend = mpl_backend
self.ets_backend = ets_backend
self.qt_api = qt_api
self.pyqt_api = pyqt_api
self.install_qt_inputhook = install_qt_inputhook
self.ignore_sip_setapi_errors = ignore_sip_setapi_errors
self.merge_output_channels = merge_output_channels
self.colorize_sys_stderr = colorize_sys_stderr
self.umd_enabled = umd_enabled
self.umd_namelist = umd_namelist
self.umd_verbose = umd_verbose
self.autorefresh_timeout = autorefresh_timeout
self.autorefresh_state = autorefresh_state
self.namespacebrowser_button = None
self.cwd_button = None
self.env_button = None
self.syspath_button = None
self.terminate_button = None
self.notification_thread = None
ExternalShellBase.__init__(self,
parent=parent,
fname=fname,
wdir=wdir,
history_filename='.history.py',
light_background=light_background,
menu_actions=menu_actions,
show_buttons_inside=show_buttons_inside,
show_elapsed_time=show_elapsed_time)
if self.pythonexecutable is None:
self.pythonexecutable = get_python_executable()
self.python_args = None
if python_args:
assert isinstance(python_args, basestring)
self.python_args = python_args
assert isinstance(arguments, basestring)
self.arguments = arguments
self.connection_file = None
self.is_ipykernel = ipykernel
if self.is_ipykernel:
interact = False
# Running our custom startup script for IPython kernels:
# (see spyderlib/widgets/externalshell/start_ipython_kernel.py)
self.fname = get_module_source_path('SMlib.widgets.externalshell',
'start_ipython_kernel.py')
self.shell.set_externalshell(self)
self.toggle_globals_explorer(False)
self.interact_action.setChecked(interact)
self.debug_action.setChecked(debug)
self.introspection_socket = None
self.is_interpreter = fname is None
if self.is_interpreter:
self.terminate_button.hide()
# Additional python path list
self.path = path
self.shell.path = path
def sphinxify(docstring, context, buildername="html"):
"""
Runs Sphinx on a docstring and outputs the processed documentation.
Parameters
----------
docstring : str
a ReST-formatted docstring
context : dict
Variables to be passed to the layout template to control how its
rendered (through the Sphinx variable *html_context*).
buildername: str
It can be either `html` or `text`.
Returns
-------
An Sphinx-processed string, in either HTML or plain text format, depending
on the value of `buildername`
"""
srcdir = mkdtemp()
srcdir = encoding.to_unicode_from_fs(srcdir)
base_name = osp.join(srcdir, "docstring")
rst_name = base_name + ".rst"
if buildername == "html":
suffix = ".html"
else:
suffix = ".txt"
output_name = base_name + suffix
# This is needed so users can type \\ on latex eqnarray envs inside raw
# docstrings
if context["right_sphinx_version"] and context["math_on"]:
docstring = docstring.replace("\\\\", "\\\\\\\\")
# Add a class to several characters on the argspec. This way we can
# highlight them using css, in a similar way to what IPython does.
argspec = context["argspec"]
for char in ["=", ",", "(", ")", "*", "**"]:
argspec = argspec.replace(char, '<span class="argspec-highlight">' + char + "</span>")
context["argspec"] = argspec
doc_file = codecs.open(rst_name, "w", encoding="utf-8")
doc_file.write(docstring)
doc_file.close()
temp_confdir = False
if temp_confdir:
# TODO: This may be inefficient. Find a faster way to do it.
confdir = mkdtemp()
confdir = encoding.to_unicode_from_fs(confdir)
generate_configuration(confdir)
else:
confdir = osp.join(get_module_source_path("SMlib.utils.inspector"))
confoverrides = {"html_context": context}
doctreedir = osp.join(srcdir, "doctrees")
sphinx_app = Sphinx(
srcdir,
confdir,
srcdir,
doctreedir,
buildername,
confoverrides,
status=None,
warning=None,
freshenv=True,
warningiserror=False,
tags=None,
)
try:
sphinx_app.build(None, [rst_name])
except SystemMessage:
output = _(
"It was not possible to generate rich text help for this " "object.</br>" "Please see it in plain text."
)
return warning(output)
# TODO: Investigate if this is necessary/important for us
if osp.exists(output_name):
output = codecs.open(output_name, "r", encoding="utf-8").read()
output = output.replace("<pre>", '<pre class="literal-block">')
else:
output = _(
"It was not possible to generate rich text help for this " "object.</br>" "Please see it in plain text."
)
return warning(output)
if temp_confdir:
shutil.rmtree(confdir, ignore_errors=True)
shutil.rmtree(srcdir, ignore_errors=True)
return output
from jinja2 import Environment, FileSystemLoader
import sphinx
from sphinx.application import Sphinx
# Local imports
from SMlib.configs.baseconfig import _, get_module_data_path, get_module_source_path
from SMlib.utils import encoding
# -----------------------------------------------------------------------------
# Globals and constants
# -----------------------------------------------------------------------------
# Note: we do not use __file__ because it won't be working in the stand-alone
# version of Spyder (i.e. the py2exe or cx_Freeze build)
CONFDIR_PATH = get_module_source_path("SMlib.utils.inspector")
CSS_PATH = osp.join(CONFDIR_PATH, "static", "css")
JS_PATH = osp.join(CONFDIR_PATH, "js")
# To let Debian packagers redefine the MathJax and JQuery locations so they can
# use their own packages for them. See Issue 1230, comment #7.
MATHJAX_PATH = get_module_data_path(
"SMlib", relpath=osp.join("utils", "inspector", JS_PATH, "mathjax"), attr_name="MATHJAXPATH"
)
JQUERY_PATH = get_module_data_path("SMlib", relpath=osp.join("utils", "inspector", JS_PATH), attr_name="JQUERYPATH")
# -----------------------------------------------------------------------------
# Utility functions
# -----------------------------------------------------------------------------
