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('src.gui.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('')
# -*- coding: utf-8 -*- # # Copyright © 2012 Spyder Development team # Licensed under the terms of the MIT or BSD Licenses # (See every file for its license) """ src.gui.utils.inspector ======================== Configuration files for the object inspector rich text mode """ import sys from src.gui.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 of 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
# colorize 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('src.gui.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 sys
from tempfile import mkdtemp
# 3rd party imports
from docutils.utils import SystemMessage as SystemMessage
from jinja2 import Environment, FileSystemLoader
from sphinx import __version__ as sphinx_version
from sphinx.application import Sphinx
# Local imports
from src.gui.baseconfig import get_module_source_path, _
from src.gui.utils import encoding
# 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('src.gui.utils.inspector')
CSS_PATH = osp.join(CONFDIR_PATH, 'static', 'css')
def is_sphinx_markup(docstring):
"""Returns whether a string contains Sphinx-style ReST markup."""
# this could be made much more clever
return ("`" in docstring or "::" in docstring)
def warning(message):
"""Print a warning message on the rich text view"""
env = Environment()
env.loader = FileSystemLoader(osp.join(CONFDIR_PATH, 'templates'))
warning = env.get_template("warning.html")
# -*- coding: utf-8 -*- # # Copyright © 2012 Spyder Development team # Licensed under the terms of the MIT or BSD Licenses # (See every file for its license) """ src.gui.utils.inspector ======================== Configuration files for the object inspector rich text mode """ import sys from src.gui.baseconfig import get_module_source_path sys.path.insert(0, get_module_source_path(__name__))
