def to_html(self, pagename, fulltext=False, drop_h1=True):
"""Return excerpt or *fulltext* as HTML after resolving references
with respect to *pagename*. By default, first `<h1>` tag is dropped
from the output. More than one can be dropped by setting *drop_h1*
to the desired number of tags to be dropped."""
if fulltext:
doctree = nodes.document({}, dummy_reporter)
deepcopy = self.doctree.deepcopy()
if isinstance(deepcopy, nodes.document):
doctree.extend(deepcopy.children)
else:
doctree.append(deepcopy)
else:
doctree = nodes.document({}, dummy_reporter)
for node in self.excerpt:
doctree.append(node.deepcopy())
app = self.ablog.app
app.env.resolve_references(doctree, pagename, app.builder)
add_permalinks, app.builder.add_permalinks = (
app.builder.add_permalinks, False)
html = html_builder_write_doc(app.builder, pagename, doctree)
app.builder.add_permalinks = add_permalinks
if drop_h1:
html = re.sub('<h1>(.*?)</h1>', '', html, count=abs(int(drop_h1)))
return html
def to_html(self, pagename, fulltext=False, drop_h1=True):
"""Return excerpt or *fulltext* as HTML after resolving references
with respect to *pagename*. By default, first `<h1>` tag is dropped
from the output. More than one can be dropped by setting *drop_h1*
to the desired number of tags to be dropped."""
if fulltext:
doctree = nodes.document({}, dummy_reporter)
deepcopy = self.doctree.deepcopy()
if isinstance(deepcopy, nodes.document):
doctree.extend(deepcopy.children)
else:
doctree.append(deepcopy)
else:
doctree = nodes.document({}, dummy_reporter)
for node in self.excerpt:
doctree.append(node.deepcopy())
app = self.ablog.app
app.env.resolve_references(doctree, pagename, app.builder)
add_permalinks, app.builder.add_permalinks = (
app.builder.add_permalinks, False)
html = html_builder_write_doc(app.builder, pagename, doctree)
app.builder.add_permalinks = add_permalinks
if drop_h1:
html = re.sub('<h1>(.*?)</h1>', '', html, count=abs(int(drop_h1)))
return html
def new_document(source_path, settings=None):
"""
Return a new empty document object.
:Parameters:
`source_path` : string
The path to or description of the source text of the document.
`settings` : optparse.Values object
Runtime settings. If none are provided, a default core set will
be used. If you will use the document object with any Docutils
components, you must provide their default settings as well. For
example, if parsing, at least provide the parser settings,
obtainable as follows::
settings = docutils.frontend.OptionParser(
components=(docutils.parsers.rst.Parser,)
).get_default_values()
"""
from docutils import frontend
if settings is None:
settings = frontend.OptionParser().get_default_values()
source_path = decode_path(source_path)
reporter = new_reporter(source_path, settings)
document = nodes.document(settings, reporter, source=source_path)
document.note_source(source_path, -1)
return document
def new_document(source_path, settings=None):
"""
Return a new empty document object.
:Parameters:
`source_path` : string
The path to or description of the source text of the document.
`settings` : optparse.Values object
Runtime settings. If none are provided, a default core set will
be used. If you will use the document object with any Docutils
components, you must provide their default settings as well. For
example, if parsing, at least provide the parser settings,
obtainable as follows::
settings = docutils.frontend.OptionParser(
components=(docutils.parsers.rst.Parser,)
).get_default_values()
"""
from docutils import frontend
if settings is None:
settings = frontend.OptionParser().get_default_values()
source_path = decode_path(source_path)
reporter = new_reporter(source_path, settings)
document = nodes.document(settings, reporter, source=source_path)
document.note_source(source_path, -1)
return document
def test_NodeMatcher():
doctree = nodes.document(None, None)
doctree += nodes.paragraph('', 'Hello')
doctree += nodes.paragraph('', 'Sphinx', block=1)
doctree += nodes.paragraph('', 'World', block=2)
doctree += nodes.literal_block('', 'blah blah blah', block=3)
# search by node class
matcher = NodeMatcher(nodes.paragraph)
assert len(doctree.traverse(matcher)) == 3
# search by multiple node classes
matcher = NodeMatcher(nodes.paragraph, nodes.literal_block)
assert len(doctree.traverse(matcher)) == 4
# search by node attribute
matcher = NodeMatcher(block=1)
assert len(doctree.traverse(matcher)) == 1
# search by node attribute (Any)
matcher = NodeMatcher(block=Any)
assert len(doctree.traverse(matcher)) == 3
# search by both class and attribute
matcher = NodeMatcher(nodes.paragraph, block=Any)
assert len(doctree.traverse(matcher)) == 2
# mismatched
matcher = NodeMatcher(nodes.title)
assert len(doctree.traverse(matcher)) == 0
def new_document():
"""There is a similar utility in docutils.utils but it supposes a file source (right?), and does not work straight for (at least) html output (?)"""
from docutils import frontend #these are only needed here
from docutils.utils import Reporter
source = None
settings = frontend.OptionParser().get_default_values()
#these needed for getting a html out - where are the defaults?
settings.xml_declaration = False
settings.embed_stylesheet = False
settings.stylesheet_path = False
settings.stylesheet = None
settings.initial_header_level = "1"
#an attempt to make docutils.nodes.NodeVisitor accept notebook classes
#this is one-to-one from docutils.utils new_document
reporter = Reporter(source,
settings.report_level,
settings.halt_level,
stream=settings.warning_stream,
debug=settings.debug,
encoding=settings.error_encoding,
error_handler=settings.error_encoding_error_handler)
document = nodes.document(settings, reporter)
return document
def _check_rst_data(self, data):
"""Returns warnings when the provided data doesn't compile."""
# the include and csv_table directives need this to be a path
source_path = self.distribution.script_name or "setup.py"
parser = Parser()
settings = frontend.OptionParser(
components=(Parser, )).get_default_values()
settings.tab_width = 4
settings.pep_references = None
settings.rfc_references = None
reporter = SilentReporter(
source_path,
settings.report_level,
settings.halt_level,
stream=settings.warning_stream,
debug=settings.debug,
encoding=settings.error_encoding,
error_handler=settings.error_encoding_error_handler,
)
document = nodes.document(settings, reporter, source=source_path)
document.note_source(source_path, -1)
try:
parser.parse(data, document)
except AttributeError as e:
reporter.messages.append(
(-1, "Could not finish the parsing: %s." % e, "", {}))
return reporter.messages
def _check_rst_data(self, data):
"""Returns warnings when the provided data doesn't compile."""
source_path = StringIO()
parser = Parser()
settings = frontend.OptionParser().get_default_values()
settings.tab_width = 4
settings.pep_references = None
settings.rfc_references = None
reporter = SilentReporter(source_path,
settings.report_level,
settings.halt_level,
stream=settings.warning_stream,
debug=settings.debug,
encoding=settings.error_encoding,
error_handler=settings.error_encoding_error_handler)
document = nodes.document(settings, reporter, source=source_path)
document.note_source(source_path, -1)
try:
parser.parse(data, document)
except AttributeError:
reporter.messages.append((-1, 'Could not finish the parsing.',
'', {}))
return reporter.messages
def _check_rst_data(self, data):
"""Returns warnings when the provided data doesn't compile."""
source_path = StringIO()
parser = Parser()
settings = frontend.OptionParser(components=(Parser,)).get_default_values()
settings.tab_width = 4
settings.pep_references = None
settings.rfc_references = None
reporter = SilentReporter(source_path,
settings.report_level,
settings.halt_level,
stream=settings.warning_stream,
debug=settings.debug,
encoding=settings.error_encoding,
error_handler=settings.error_encoding_error_handler)
document = nodes.document(settings, reporter, source=source_path)
document.note_source(source_path, -1)
try:
parser.parse(data, document)
except AttributeError as e:
reporter.messages.append(
(-1, 'Could not finish the parsing: %s.' % e, '', {}))
return reporter.messages
def test_NodeMatcher():
doctree = nodes.document(None, None)
doctree += nodes.paragraph('', 'Hello')
doctree += nodes.paragraph('', 'Sphinx', block=1)
doctree += nodes.paragraph('', 'World', block=2)
doctree += nodes.literal_block('', 'blah blah blah', block=3)
# search by node class
matcher = NodeMatcher(nodes.paragraph)
assert len(list(doctree.traverse(matcher))) == 3
# search by multiple node classes
matcher = NodeMatcher(nodes.paragraph, nodes.literal_block)
assert len(list(doctree.traverse(matcher))) == 4
# search by node attribute
matcher = NodeMatcher(block=1)
assert len(list(doctree.traverse(matcher))) == 1
# search by node attribute (Any)
matcher = NodeMatcher(block=Any)
assert len(list(doctree.traverse(matcher))) == 3
# search by both class and attribute
matcher = NodeMatcher(nodes.paragraph, block=Any)
assert len(list(doctree.traverse(matcher))) == 2
# mismatched
matcher = NodeMatcher(nodes.title)
assert len(list(doctree.traverse(matcher))) == 0
# search with Any does not match to Text node
matcher = NodeMatcher(blah=Any)
assert len(list(doctree.traverse(matcher))) == 0
def to_html(self, pagename, fulltext=False):
"""Return excerpt as HTML after resolving references with respect to
*pagename*."""
if fulltext:
doctree = nodes.document({}, dummy_reporter)
deepcopy = self.doctree.deepcopy()
if isinstance(deepcopy, nodes.document):
doctree.extend(deepcopy.children)
else:
doctree.append(deepcopy)
else:
doctree = nodes.document({}, dummy_reporter)
for node in self.excerpt:
doctree.append(node.deepcopy())
app = self.ablog.app
app.env.resolve_references(doctree, pagename, app.builder)
html = html_builder_write_doc(app.builder, pagename, doctree)
return html
def summary(self, pagename):
"""Return summary after resolving references with respect to
*pagename*."""
doctree = nodes.document({}, dummy_reporter)
for node in self.excerpt:
doctree.append(node.deepcopy())
app = self.ablog.app
app.env.resolve_references(doctree, pagename, app.builder)
return html_builder_write_doc(app.builder, pagename, doctree)
def to_html(self, pagename, fulltext=False):
"""Return excerpt as HTML after resolving references with respect to
*pagename*."""
if fulltext:
doctree = nodes.document({}, dummy_reporter)
deepcopy = self.doctree.deepcopy()
if isinstance(deepcopy, nodes.document):
doctree.extend(deepcopy.children)
else:
doctree.append(deepcopy)
else:
doctree = nodes.document({}, dummy_reporter)
for node in self.excerpt:
doctree.append(node.deepcopy())
app = self.ablog.app
app.env.resolve_references(doctree, pagename, app.builder)
html = html_builder_write_doc(app.builder, pagename, doctree)
return html
def new_document(source_path, settings=None):
"""
Return a new empty document object.
:Parameters:
`source` : string
The path to or description of the source text of the document.
`settings` : optparse.Values object
Runtime settings. If none provided, a default set will be used.
"""
if settings is None:
settings = frontend.OptionParser().get_default_values()
reporter = new_reporter(source_path, settings)
document = nodes.document(settings, reporter, source=source_path)
document.note_source(source_path, -1)
return document
def new_document(source_path, settings=None):
"""
Return a new empty document object.
:Parameters:
`source` : string
The path to or description of the source text of the document.
`settings` : optparse.Values object
Runtime settings. If none provided, a default set will be used.
"""
if settings is None:
settings = frontend.OptionParser().get_default_values()
reporter = new_reporter(source_path, settings)
document = nodes.document(settings, reporter, source=source_path)
document.note_source(source_path, -1)
return document
def new_document(source_path: str, settings: Any = None) -> nodes.document:
"""Return a new empty document object. This is an alternative of docutils'.
This is a simple wrapper for ``docutils.utils.new_document()``. It
caches the result of docutils' and use it on second call for instanciation.
This makes an instantiation of document nodes much faster.
"""
global __document_cache__
if __document_cache__ is None:
__document_cache__ = docutils.utils.new_document(source_path)
if settings is None:
# Make a copy of ``settings`` from cache to accelerate instansiation
settings = copy(__document_cache__.settings)
# Create a new instance of nodes.document using cached reporter
document = nodes.document(settings, __document_cache__.reporter, source=source_path)
document.note_source(source_path, -1)
return document
def new_document(source, settings=None):
"""
Return a new empty document object.
:Parameters:
`source` : string
The path to or description of the source text of the document.
`settings` : optparse.Values object
Runtime settings. If none provided, a default set will be used.
"""
if settings is None:
settings = frontend.OptionParser().get_default_values()
reporter = Reporter(source, settings.report_level, settings.halt_level,
stream=settings.warning_stream, debug=settings.debug,
encoding=settings.error_encoding,
error_handler=settings.error_encoding_error_handler)
document = nodes.document(settings, reporter, source=source)
document.note_source(source, -1)
return document
def _check_rst_data(self, data):
"""Returns warnings when the provided data doesn't compile."""
# the include and csv_table directives need this to be a path
source_path = self.distribution.script_name or 'setup.py'
parser = Parser()
settings = frontend.OptionParser(components=(Parser,)).get_default_values()
settings.tab_width = 4
settings.pep_references = None
settings.rfc_references = None
reporter = SilentReporter(source_path,
settings.report_level,
settings.halt_level,
stream=settings.warning_stream,
debug=settings.debug,
encoding=settings.error_encoding,
error_handler=settings.error_encoding_error_handler)
document = nodes.document(settings, reporter, source=source_path)
document.note_source(source_path, -1)
try:
def new_document(source_path, settings=None):
# type: (unicode, Any) -> nodes.document
"""Return a new empty document object. This is an alternative of docutils'.
This is a simple wrapper for ``docutils.utils.new_document()``. It
caches the result of docutils' and use it on second call for instanciation.
This makes an instantiation of document nodes much faster.
"""
global __document_cache__
if __document_cache__ is None:
__document_cache__ = docutils.utils.new_document(source_path)
if settings is None:
# Make a copy of ``settings`` from cache to accelerate instansiation
settings = copy(__document_cache__.settings)
# Create a new instance of nodes.document using cached reporter
document = nodes.document(settings, __document_cache__.reporter, source=source_path)
document.note_source(source_path, -1)
return document
def new_document(
source_path: str, settings: Any = None
) -> Tuple[nodes.document, JSONReporter]:
"""Return a new empty document object.
Replicates ``docutils.utils.new_document``, but uses JSONReporter,
which is also returned
Parameters
----------
source_path : str
The path to or description of the source text of the document.
settings : optparse.Values
Runtime settings. If none are provided, a default core set will
be used. If you will use the document object with any Docutils
components, you must provide their default settings as well. For
example, if parsing, at least provide the parser settings,
obtainable as follows::
settings = docutils.frontend.OptionParser(
components=(docutils.parsers.rst.Parser,)
).get_default_values()
"""
# TODO cache creation, as in sphinx.util.docutils.new_document, possibly using a
# 'partial' lru_cache, as in https://stackoverflow.com/a/37611009/5033292
if settings is None:
settings = OptionParser().get_default_values()
# TODO can probably remove decode_path, given python 3 only support
source_path = decode_path(source_path)
reporter = JSONReporter(
source_path,
settings.report_level,
settings.halt_level,
stream=settings.warning_stream,
debug=settings.debug,
encoding=settings.error_encoding,
error_handler=settings.error_encoding_error_handler,
)
document = nodes.document(settings, reporter, source=source_path)
document.note_source(source_path, -1)
return document, reporter
def _build_node(node):
original_header_level = self.docsettings.initial_header_level
# bump initial header level to two
self.docsettings.initial_header_level = 2
# indicate that we're building for the wizard fragements.
# This changes url generation and more.
# Embed pygments colors as inline styles
original_args = self.highlighter.formatter_args
self.highlighter.formatter_args = original_args.copy()
self.highlighter.formatter_args['noclasses'] = True
try:
sub_doc = document(self.docsettings, doctree.reporter)
sub_doc += node
destination = StringOutput(encoding='utf-8')
self.current_docname = docname
self.docwriter.write(sub_doc, destination)
self.docwriter.assemble_parts()
rv.append(self.docwriter.parts['fragment'])
finally:
self.highlighter.formatter_args = original_args
self.docsettings.initial_header_level = original_header_level
def new_document(source, settings=None):
"""
Return a new empty document object.
:Parameters:
`source` : string
The path to or description of the source text of the document.
`settings` : optparse.Values object
Runtime settings. If none provided, a default set will be used.
"""
if settings is None:
settings = frontend.OptionParser().get_default_values()
reporter = Reporter(source,
settings.report_level,
settings.halt_level,
stream=settings.warning_stream,
debug=settings.debug,
encoding=settings.error_encoding,
error_handler=settings.error_encoding_error_handler)
document = nodes.document(settings, reporter, source=source)
document.note_source(source, -1)
return document
def _build_node(node):
original_header_level = self.docsettings.initial_header_level
# bump initial header level to two
self.docsettings.initial_header_level = 2
# indicate that we're building for the wizard fragements.
# This changes url generation and more.
# Embed pygments colors as inline styles
original_args = self.highlighter.formatter_args
self.highlighter.formatter_args = original_args.copy()
self.highlighter.formatter_args['noclasses'] = True
try:
sub_doc = document(self.docsettings,
doctree.reporter)
sub_doc += node
destination = StringOutput(encoding='utf-8')
self.current_docname = docname
self.docwriter.write(sub_doc, destination)
self.docwriter.assemble_parts()
rv.append(self.docwriter.parts['fragment'])
finally:
self.highlighter.formatter_args = original_args
self.docsettings.initial_header_level = original_header_level
source = None
settings = frontend.OptionParser().get_default_values()
settings.xml_declaration = False
settings.embed_stylesheet = False
settings.stylesheet_path = False
settings.stylesheet = None
settings.initial_header_level = "1"
reporter = Reporter(source,
settings.report_level,
settings.halt_level,
stream=settings.warning_stream,
debug=settings.debug,
encoding=settings.error_encoding,
error_handler=settings.error_encoding_error_handler)
document = nodes.document(settings, reporter)
title = nodes.title(text="This is the title")
subtitle = nodes.subtitle(text=".. with a subtitle")
introduction = nodes.section()
start = nodes.paragraph(text="The introduction starts with this.")
introduction += start
background = nodes.section()
background += nodes.paragraph(
text="This paragraph starts the second section, background.")
document += [title, subtitle, introduction, background]
#print str(document)
