Merge branch 'release-0.6.0'

docs/source/changelog.rst

@@ -1,6 +1,19 @@
 Changelog
 #######################################
 
+0.6.0
+=======================================
+
+Features:
+
+  - Added :doc:`processors/image-inline` processor, intended for use in tables.
+  - Added :doc:`processors/scratch-inline` processor for inline scratch support.
+
+Fixes:
+
+  - Removed ``beautifulsoup4`` dependency.
+  - Typo in VertoResult documentation (*heading_root* -> *heading_tree*).
+
 0.5.3
 =======================================
 

docs/source/contributing.rst

@@ -141,7 +141,7 @@ There are two types of generic processors:
   - tags (``generic_tag``): which match ``{<processor_name> <args>}`` in the markdown text replacing with the given html-template.
   - containers (``generic_container``): which are a pair of tags which capture the content between the tags for the html-template. A generic container's opening tag specifies the arguments, while the closing tag only has the ``end`` argument allowing for the content to contain generic containers.
 
-To create a new processor that uses the generic processors the processor must be added to the ``processor-info.json`` file and an associated html-template must be created.
+To create a new processor that uses the generic processors the processor must be added to the ``processor-info.json`` file and an associated html-template must be created. The template must only have one root level node after rendering.
 
 How to make a JSON Definition
 ++++++++++++++++++++++++++++++++++++++
@@ -286,7 +286,7 @@ The logic for each processor belongs in the ``processors/`` directory, and there
 - The processor's relevant information (regex pattern, required parameters etc) should be included in ``processor-info.json``.
 - If it should be a default processor, it should be added to the frozenset of ``DEFAULT_PROCESSORS`` in ``Verto.py``.
 - The relevant list in ``extendMarkdown()`` in ``VertoExtension.py`` (see `OrderedDict in the Markdown API docs`_ for manipulating processor order).
-- The processor's template should be added to ``html-templates`` using the Jinja2 template engine syntax for variable parameters.
+- The processor's template should be added to ``html-templates`` using the Jinja2 template engine syntax for variable parameters. A valid template will only have one root level node after rendering, if more root nodes are necessary the remove tag can be used as the root node which will be removed later.
 - Any errors should have appropriate classes in the ``errors\`` directory, they should be well described by their class name such that for an expert knows immediately what to do to resolve the issue, otherwise a message should be used to describe the exact causation of the error for a novice.
 
 

docs/source/processors/image-inline.rst

@@ -0,0 +1,78 @@
+Inline Image
+#######################################
+
+**Processor name:** ``image-inline``
+
+.. note::
+
+    The inline image tag allows for the use of images inside tables, *etc* without causing style errors. The tag functions almost exactly the same as the ``image`` tag except for the alignment argument.
+
+You can include an inline image using the following text tag:
+
+.. literalinclude:: ../../../verto/tests/assets/image-inline/doc_example_basic_usage.md
+    :language: none
+
+Required Tag Parameters
+***************************************
+
+- ``file-path`` - The path to the image.
+
+    - Each file-path provided is added to the ``images`` set in required files stored by Verto. The set of filepaths can be accessed after conversion, see :ref:`accessing_verto_data`.
+    - **Note:** If the given link is a relative (a link that doesn't start with ``http:``), the link will be rendered with a Django static command. For example, the link ``images/example.png`` would be rendered as ``{% static 'images/example.png' %}`` This can be overriden, see the override section below.
+
+Optional Tag Parameters
+***************************************
+
+- ``alt`` - Description text of the image used when an image is not displayed, or can be read when using a screen reader (for those with reading difficulties).
+- ``caption`` - Lists the given text as a caption under the image.
+- ``caption-link`` (requires caption parameter) - Converts the caption text into a link to the given caption link URL.
+- ``source`` (optional) - Adds the text 'Source' under the image with a link to the given source URL. Displays after the caption if a caption is given.
+- ``hover-text`` - Additional text to be displayed when the user hovers their cursor over the image (note this won't appear on touch devices so use sparingly).
+
+The default HTML for image is:
+
+.. literalinclude:: ../../../verto/html-templates/image-inline.html
+    :language: css+jinja
+
+Using the following example tag:
+
+.. literalinclude:: ../../../verto/tests/assets/image-inline/doc_example_basic_usage.md
+    :language: none
+
+The resulting HTML would be:
+
+.. literalinclude:: ../../../verto/tests/assets/image-inline/doc_example_basic_usage_expected.html
+    :language: html
+
+Overriding HTML for Images
+***************************************
+
+When overriding the HTML for images, the following Jinja2 placeholders are available:
+
+- ``{{ file_path }}`` - The location for the path to the URL.
+- ``{{ alt }}`` - The alternative text for the image.
+- ``{{ hover_text }}`` - The text to display when the user hovers over the image (see `image title attribute <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title>`_).
+- ``{{ caption }}`` - The text for the image caption.
+- ``{{ caption_link }}`` - The URL for the caption link .
+- ``{{ source_link }}`` - The URL for the source .
+
+If the ``file_path`` provided is a relative link, the link is passed through the ``relative-file-link.html`` template.
+The default HTML for relative images is:
+
+.. literalinclude:: ../../../verto/html-templates/relative-file-link.html
+  :language: css+jinja
+
+For example, providing the following HTML:
+
+.. literalinclude:: ../../../verto/tests/assets/image-inline/doc_example_override_html_template.html
+   :language: css+jinja
+
+with the following tag:
+
+.. literalinclude:: ../../../verto/tests/assets/image-inline/doc_example_override_html.md
+   :language: none
+
+would result in:
+
+.. literalinclude:: ../../../verto/tests/assets/image-inline/doc_example_override_html_expected.html
+   :language: html

docs/source/processors/index.rst

@@ -21,12 +21,14 @@ The following pages covers how to use the available processors within Markdown t
     glossary-link
     heading
     image
+    image-inline
     interactive
     panel
     relative-link
     remove-title
     save-title
     scratch
+    scratch-inline
     table-of-contents
     video
 

docs/source/processors/scratch-inline.rst

@@ -0,0 +1,87 @@
+Scratch (Inline)
+#######################################
+
+**Processor name:** ``scratch-inline``
+
+.. note::
+
+  The inline scratch processor works similarly to the default :doc:`scratch` processor except that it matches inline codeblocks instead and requires a colon after the scratch tag.
+
+.. danger::
+
+  Scratch blocks require an understanding of the Scratch programming language and how Verto is integrated with other systems. The use of this processor requires co-ordination between authors and developers to achieve the desired functionality.
+
+.. note::
+
+    The following examples assume usage of the fenced code extension, by having
+    ``markdown.extensions.fenced_code`` in the list of extensions given to Verto.
+
+You can include an image of Scratch blocks using
+`Scratch Block Plugin notation`_ using the following notation:
+
+.. literalinclude:: ../../../verto/tests/assets/scratch-inline/doc_example_basic_usage.md
+    :language: none
+
+to produce the following image with the ``scratch:`` stripped:
+
+.. image:: ../images/scratch_inline_example.png
+
+which is inserted between the paragraph text.
+
+
+You can test the output of your Scratch block text at
+`scratchblocks.github.io`_.
+You can also generate Scratch block text from a published Scratch project at
+`scratchblocks.github.io/generator/`_.
+
+.. warning::
+
+    Verto doesn't create the Scratch images, but saves data for another system
+    (for example: Django) to create the images.
+    See :ref:`accessing-scratch-image-data` section in the scratch documentation.
+
+
+The default HTML for scratch blocks is:
+
+.. literalinclude:: ../../../verto/html-templates/scratch-inline.html
+    :language: css+jinja
+
+Using the following example tag:
+
+.. literalinclude:: ../../../verto/tests/assets/scratch-inline/doc_example_basic_usage.md
+    :language: none
+
+The resulting HTML would be:
+
+.. literalinclude:: ../../../verto/tests/assets/scratch-inline/doc_example_basic_usage_expected.html
+    :language: html
+
+
+Overriding HTML for Scratch
+***************************************
+
+When overriding the HTML for Scratch code, the following Jinja2 placeholders are available:
+
+- ``{{ hash }}`` - The hash of the Scratch code-blocks used in the expected filename.
+
+**Example**
+
+For example, providing the following HTML:
+
+.. literalinclude:: ../../../verto/tests/assets/scratch-inline/doc_example_override_html_template.html
+    :language: css+jinja
+
+with the following tag:
+
+.. literalinclude:: ../../../verto/tests/assets/scratch-inline/doc_example_override_html.md
+    :language: none
+
+would result in:
+
+.. literalinclude:: ../../../verto/tests/assets/scratch-inline/doc_example_override_html_expected.html
+    :language: html
+
+.. _Scratch Block Plugin notation: https://wiki.scratch.mit.edu/wiki/Block_Plugin
+.. _scratchblocks.github.io: https://scratchblocks.github.io/#when%20flag%20clicked%0Aclear%0Aforever%0Apen%20down%0Aif%20%3C%3Cmouse%20down%3F%3E%20and%20%3Ctouching%20%5Bmouse-pointer%20v%5D%3F%3E%3E%20then%0Aswitch%20costume%20to%20%5Bbutton%20v%5D%0Aelse%0Aadd%20(x%20position)%20to%20%5Blist%20v%5D%0Aend%0Amove%20(foo)%20steps%0Aturn%20ccw%20(9)%20degrees
+.. _scratchblocks.github.io/generator/: https://scratchblocks.github.io/generator/
+.. _scratchblocks: https://github.com/scratchblocks/scratchblocks

docs/source/processors/scratch.rst

@@ -43,7 +43,7 @@ You can also generate Scratch block text from a published Scratch project at
     See :ref:`accessing-scratch-image-data` section below.
 
 
-The default HTML for button links is:
+The default HTML for scratch blocks is:
 
 .. literalinclude:: ../../../verto/html-templates/scratch.html
     :language: css+jinja
@@ -119,7 +119,7 @@ Overriding HTML for Scratch
 
 When overriding the HTML for Scratch code, the following Jinja2 placeholders are available:
 
-- ``{{ hash }}`` - A list of hashes of the Scratch code-blocks used in the expected filename(s).
+- ``{{ images }}`` - A list of hashes of the Scratch code-blocks used in the expected filename(s).
 
 **Example**
 

docs/source/usage.rst

@@ -86,7 +86,7 @@ The following attributes are available:
 
   - See :ref:`accessing-scratch-image-data` for data from Scratch processor.
 
-- ``heading_root`` - A tuple of namedtuples which describes the tree of headings, as generated by our heading processor. Each namedtuple contains a ``title`` (string), ``title_slug`` (string), ``level`` (integer) and ``children`` (tuple of nodes).
+- ``heading_tree`` - A tuple of namedtuples which describes the tree of headings, as generated by our heading processor. Each namedtuple contains a ``title`` (string), ``title_slug`` (string), ``level`` (integer) and ``children`` (tuple of nodes).
 
   - For example the heading root after a conversion of a file:
 

requirements.txt

@@ -1,10 +1,9 @@
 # Required dependencies for Verto (installed automatically in setup.py)
 markdown==2.6.8
-beautifulsoup4==4.5.3
 Jinja2==2.9.6
 python-slugify==1.2.4
 setuptools==35.0.2
 
 # Required dependencies for building documentation
-sphinx==1.5.5
+sphinx==1.6.1
 sphinx_rtd_theme==0.2.4

setup.py

@@ -31,7 +31,6 @@
     include_package_data=True,
     install_requires=[
         'markdown>=2.6.8',
-        'beautifulsoup4>=4.5.3',
         'Jinja2>=2.9.6',
         'python-slugify>=1.2.4'
     ]

verto/Verto.py

@@ -11,11 +11,13 @@
     'heading',
     'iframe',
     'image',
+    'image-inline',
     'interactive',
     'panel',
     'relative-link',
     'save-title',
     'scratch',
+    'scratch-inline',
     'table-of-contents',
     'video'
 })

verto/VertoExtension.py

@@ -3,6 +3,7 @@
 
 from verto.processors.CommentPreprocessor import CommentPreprocessor
 from verto.processors.VideoBlockProcessor import VideoBlockProcessor
+from verto.processors.ImageInlinePattern import ImageInlinePattern
 from verto.processors.ImageBlockProcessor import ImageBlockProcessor
 from verto.processors.InteractiveBlockProcessor import InteractiveBlockProcessor
 from verto.processors.RelativeLinkPattern import RelativeLinkPattern
@@ -15,6 +16,7 @@
 from verto.processors.JinjaPostprocessor import JinjaPostprocessor
 from verto.processors.HeadingBlockProcessor import HeadingBlockProcessor
 from verto.processors.ScratchTreeprocessor import ScratchTreeprocessor
+from verto.processors.ScratchInlineTreeprocessor import ScratchInlineTreeprocessor
 from verto.processors.ScratchCompatibilityPreprocessor import ScratchCompatibilityPreprocessor
 from verto.processors.ScratchCompatibilityPreprocessor import FENCED_BLOCK_RE_OVERRIDE
 from verto.processors.GenericTagBlockProcessor import GenericTagBlockProcessor
@@ -181,10 +183,12 @@ def buildProcessors(self, md, md_globals):
         self.inlinepatterns = [  # A special treeprocessor
             ['relative-link', RelativeLinkPattern(self, md), '_begin'],
             ['glossary-link', GlossaryLinkPattern(self, md), '_begin'],
+            ['image-inline', ImageInlinePattern(self, md), '_begin']
         ]
         scratch_ordering = '>inline' if 'hilite' not in self.compatibility else '<hilite'
         self.treeprocessors = [
             ['scratch', ScratchTreeprocessor(self, md), scratch_ordering],
+            ['scratch-inline', ScratchInlineTreeprocessor(self, md), '>inline'],
         ]
         self.postprocessors = []
         self.buildGenericProcessors(md, md_globals)

verto/__init__.py

@@ -1,4 +1,4 @@
 # flake8: noqa
 from .Verto import Verto
 
-__version__ = '0.5.3'
+__version__ = '0.6.0'

verto/html-templates/image-inline.html

@@ -0,0 +1,13 @@
+<div>
+<img src="{{ file_path }}"
+{% if alt %} alt="{{ alt }}" {% endif -%}
+{%- if hover_text %} title="{{ hover_text }}" {% endif -%}>
+{% if caption and caption_link -%}
+<p><a href="{{ caption_link }}">{{ caption }}</a></p>
+{%- elif caption -%}
+<p>{{ caption }}</p>
+{%- endif -%}
+{%- if source_link -%}
+<p><a href="{{ source_link }}">Source</a></p>
+{%- endif -%}
+</div>

verto/html-templates/scratch-inline.html

@@ -0,0 +1 @@
+<object type="image/svg+xml" data="{% autoescape false -%}{{ "{% static '" }}scratch-blocks-{{ hash }}.svg{{ "' %}" }}{%- endautoescape %}"></object>

verto/processor-info.json

@@ -155,6 +155,36 @@
           }
         }
     },
+    "image-inline": {
+        "class": "custom",
+        "pattern": "\\{image-inline (?P<args>[^\\}]*)\\}",
+        "arguments": {
+          "file-path": {
+            "required": true,
+            "dependencies": []
+          },
+          "alt": {
+            "required": false,
+            "dependencies": []
+          },
+          "caption": {
+            "required": false,
+            "dependencies": []
+          },
+          "caption-link": {
+            "required": false,
+            "dependencies": ["caption"]
+          },
+          "source": {
+            "required": false,
+            "dependencies": []
+          },
+          "hover-text": {
+            "required": false,
+            "dependencies": []
+          }
+        }
+    },
     "interactive": {
         "class": "custom",
         "arguments": {
@@ -232,12 +262,16 @@
           "pattern": "(?P<fence>^(?:~{3,}|`{3,}))[ ]*scratch(?P<options>(:[^:\\n$]+)*)[ ]*(hl_lines=(?P<quot>\"|')(?P<hl_lines>.*?)(?P=quot))?[ ]*}?[ ]*\n(?P<code>.*?)(?<=\n)(?P=fence)[ ]*$"
         }
     },
+    "scratch-inline": {
+        "class": "custom",
+        "pattern": "^scratch:"
+    },
     "style": {
       "class": "custom",
-      "block_pattern": "\\{{{block} ?([^\\}}]*)\\}}",
-      "inline_pattern": "\\{{{inline} ?([^\\}}]*)\\}}",
+      "block_pattern": "\\{{{block}( ([^\\}}]*))?\\}}",
+      "inline_pattern": "\\{{{inline}( ([^\\}}]*))?\\}}",
       "strings": {
-        "inline": ["glossary-link"],
+        "inline": ["glossary-link", "image-inline"],
         "block": ["boxed-text", "button-link", "comment", "conditional", "iframe", "image", "interactive", "panel", "table-of-contents", "video"]
       }
     },

verto/processors/ImageBlockProcessor.py

@@ -66,7 +66,6 @@ def run(self, parent, blocks):
         context = dict()
         context['file_path'] = file_path
         context['alt'] = argument_values.get('alt', None)
-        context['title'] = argument_values.get('title', None)
         context['caption'] = argument_values.get('caption', None)
         context['caption_link'] = argument_values.get('caption-link', None)
         context['source_link'] = argument_values.get('source', None)