`` and ``
`` HTML elements which set
# the left margin of indented text based on how many spaces (0.5 em = 1 space).
#
# +--------------------------+-------------------------+-----------------------------------+
# + Python source + Translated to reST | Translated to (simplified) HTML |
# +==========================+=========================+===================================+
# | .. code-block:: Python3 | No indent | .. code-block:: html |
# | | | |
# | # No indent | .. raw:: html |
No indent
|
# | # Two space indent | |
|
# | # Three space indent |
Two space indent |
# | | "margin-left:1.0em;"> |
|
# | | |
|
# | | Two space indent |
Three space indent
|
# | | |
|
# | | .. raw:: html | |
# | | | |
# | |
| |
# | | | |
# | | Three space indent | |
# | | | |
# | | .. raw:: html | |
# | | | |
# | |
| |
# +--------------------------+-------------------------+-----------------------------------+
# Following either a fenced code block or a raw block, care must be taken to
# separate these blocks' content from indented comments which follow them. For
# example, the following code:
#
# +--------------------------+-------------------------+-----------------------------------+
# + Python source + Translated to reST | Translated to (simplified) HTML |
# +==========================+=========================+===================================+
# | .. code-block:: Python3 | .. fenced-code:: | .. code-block:: html |
# | | | |
# | def foo(): | Beginning fence |
def foo(): |
# | # Indented comment | def foo(): | Ending fence |
# | | Ending fence | |
# | | | |
# | | Indented comment | |
# +--------------------------+-------------------------+-----------------------------------+
#
# Notice that the ``Ending fence`` ends up in the resulting HTML! To fix this,
# simply add an unindented `reST comment
# `_ after a block.
#
# +--------------------------+-------------------------+-----------------------------------+
# + Python source + Translated to reST | Translated to (simplified) HTML |
# +==========================+=========================+===================================+
# | .. code-block:: Python3 | .. fenced-code:: | .. code-block:: html |
# | | | |
# | def foo(): | Beginning fence | def foo(): |
# | # Indented comment | def foo(): |
|
# | | Ending fence | |
# | | | Indented comment |
# | | .. |
|
# | | | |
# | | Indented comment | |
# +--------------------------+-------------------------+-----------------------------------+
#
# Mixed code and comments
# ^^^^^^^^^^^^^^^^^^^^^^^
# Note that mixing code and comments is hard: reST will still apply some of
# its parsing rules to an inline code block or inline literal, meaning
# that leading or trailing spaces and backticks will not be preserved,
# instead parsing incorrectly. For example ::
#
# :code:` Testing `
#
# renders incorrectly. So, mixed lines are simply translated as code, meaning
# reST markup can't be applied to the comments.
#
# .. _summary_and_implementation:
#
# Summary and implementation
# ^^^^^^^^^^^^^^^^^^^^^^^^^^
# This boils down to the following basic rules:
#
# #. Code blocks must be preceeded and followed by a removed marker (fences).
#
# #. Comments must be preeceded and followed by reST which sets the left
# margin based on the number of spaces before the comment.
#
# #. Both must be followed by an empty, unindented `reST comment`_.
#
# .. _generate_rest:
#
# Generate reST from the classified code. To do this, create a state machine,
# where current_type defines the state. When the state changes, exit the
# previous state (output a closing fence or closing ``
``, then enter the
# new state (output a fenced code block or an opening ``
``.
def _generate_rest(
# An iterable of (type, string) pairs, one per line.
classified_lines,
# .. _out_file:
#
# A file-like output to which the reST text is written.
out_file):
# Keep track of the current type. Begin with a 0-indent comment.
current_type = -2
# Keep track of the current line number.
line = 1
for type_, string in classified_lines:
_debug_print('type_ = {}, line = {}, string = {}\n'.format(type_, line, [string]))
# See if there's a change in state.
if current_type != type_:
# Exit the current state.
_exit_state(current_type, out_file)
# Enter the new state.
#
# Code state: emit the beginning of a fenced block.
if type_ == -1:
out_file.write('\n.. fenced-code::\n\n Beginning fence\n')
# Comment state: emit an opening indent for non-zero indents.
else:
# Add an indent if needed.
if type_ > 0:
out_file.write('\n.. raw:: html\n\n'
'
\n\n'.format(0.5*type_))
# Specify the line number in the source, so that errors will be
# accurately reported. This isn't necessary in code blocks,
# since errors can't occur.
#
# After this directive, the following text may be indented,
# which would make it a part of the ``set-line`` directive! So,
# include an empty comment to terminate the ``set-line``, making
# any following indents a separate syntatical element. See the
# end of `reST comment syntax `_
# for more discussion.
out_file.write('\n.. set-line:: {}\n\n..\n\n'.format(line - 4))
# Output string based on state. All code needs an inital space to
# place it inside the fenced-code block.
if type_ == -1:
out_file.write(' ')
out_file.write(string)
# Update the state.
current_type = type_
line += 1
# When done, exit the last state.
_exit_state(current_type, out_file)
#
#
# Supporting routines
# """""""""""""""""""
# Output text produce when exiting a state. Supports generate_rest_ above.
def _exit_state(
# The type (classification) of the last line.
type_,
# See out_file_.
out_file):
# Code state: emit an ending fence.
if type_ == -1:
out_file.write(' Ending fence\n\n..\n\n')
# Comment state: emit a closing indent.
elif type_ > 0:
out_file.write('\n.. raw:: html\n\n
\n\n..\n\n')
# Initial state. Nothing needed.
else:
pass
#
#
# Supporting reST directives
# """"""""""""""""""""""""""
# Create a fenced code block: the first and last lines are presumed to be
# fences, which keep the parser from discarding whitespace. Drop these, then
# treat everything else as code.
#
# See the `directive docs
#
`_ for more
# information.
class _FencedCodeBlock(CodeBlock):
def run(self):
# The content must contain at least two lines (the fences).
if len(self.content) < 2:
raise self.error('Fenced code block must contain at least two lines.')
# Remove the fences.
self.content = self.content[1:-1]
#
# By default, the Pygments `stripnl
# `_ option is True, causing Pygments
# to drop any empty lines. The reST parser converts a line containing
# only spaces to an empty line, which will then be stripped by Pygments
# if these are leading or trailing newlines. So, add a space back in to
# keep these lines from being dropped.
#
# So, first add spaces from the beginning of the lines until we reach
# the first non-blank line.
processedAllContent = True
for i, content in enumerate(self.content):
if content:
processedAllContent = False
break
self.content[i] = ' '
# If we've seen all the content, then don't do it again -- we'd be
# adding unnecessary spaces. Otherwise, walk from the end of the content
# backwards, adding spaces until the first non-blank line.
if not processedAllContent:
for i, _ in enumerate(self.content):
# Recall Python indexing: while 0 is the first elemment in a
# list, -1 is the last element, so offset all indices by -1.
if self.content[-i - 1]:
break
self.content[-i - 1] = ' '
# Now, process the resulting contents as a code block.
nodeList = CodeBlock.run(self)
# Sphinx fix: if the current `highlight
# `_ language is ``python``,
# "Normal Python code is only highlighted if it is parseable" (quoted
# from the previous link). This means code snippets, such as
# ``def foo():`` won't be highlighted: Python wants ``def foo(): pass``,
# for example. To get around this, setting the ``highlight_args`` option
# "force"=True skips the parsing. I found this in
# ``Sphinx.highlighting.highlight_block`` (see the ``force`` argument)
# and in ``Sphinx.writers.html.HTMLWriter.visit_literal_block``, where
# the ``code-block`` directive (which supports fragments of code, not
# just parsable code) has ``highlight_args['force'] = True`` set. This
# should be ignored by docutils, so it's done for both Sphinx and
# docutils. **Note:** This is based on examining Sphinx 1.3.1 source
# code.
#
# Note that the nodeList returned by the CodeBlock directive contains
# only a single ``literal_block`` node. The setting should be applied to
# it.
nodeList[0]['highlight_args'] = {'force' : True}
return nodeList
# This directive allows changing the line number at which errors will be
# reported. ``.. set-line:: 10`` makes the current line report as line 10,
# regardless of its actual location in the file.
class _SetLine(Directive):
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = False
option_spec = {}
has_content = False
def run(self):
line = int(self.arguments[0])
# The ``input_lines`` class (see docutils.statemachine.ViewList)
# maintains two lists, ``data`` and ``items``. ``data`` is a list of
# strings, one per line, of reST to process. ``items`` is a list of
# ``(source, offset)`` giving the source of each line and the offset of
# each line from the beginning of its source. Modifying the offset will
# change the reported error location.
il = self.state_machine.input_lines
# However, directly modifying ``input_lines`` produces no effect: the
# root ``input_lines`` must be modified. Find it.
while il.parent:
il = il.parent
# Now, determine the index of this directive's line in the parent
# ``input_offset`` class.
current_line = (self.state_machine.line_offset +
self.state_machine.input_offset)
# Walk from this line to the end of the file, rewriting the offset (that
# is, the effective line number).
items = il.items
for i in range(current_line, len(items)):
(source, offset) = items[i]
items[i] = (source, line)
line += 1
# This directive create no nodes.
return []
# Register the new fenced code block directive with docutils.
directives.register_directive('fenced-code', _FencedCodeBlock)
directives.register_directive('set-line', _SetLine)