Merge branch 'release/0.8.0'

README.rst

@@ -19,7 +19,9 @@ markdown:
 
   Example Paragraph
 
-  {panel type="example" title="Example Panel"}
+  {panel type="example"}
+
+  # Example Panel
 
   {image file-path="http://placehold.it/350x150" caption="Example Image"}
 

docs/source/changelog.rst

@@ -1,6 +1,31 @@
 Changelog
 #######################################
 
+0.8.0
+=======================================
+
+- Modify :doc:`processors/interactive` processor for translating text, by required text between start and end tags for whole page interactives.
+- Modify Verto parameters available on creation to allow modification of default required parameters for each processor.
+- Dependency updates:
+
+  - Update ``setuptools`` to 40.2.0.
+  - Update ``sphinx`` to 1.7.7.
+  - Update ``sphinx_rtx_theme`` to 0.4.1.
+
+0.7.4
+=======================================
+
+- Modify :doc:`processors/interactive` processor to use ``slug`` rather than ``name`` to identify interactives
+- Modify :doc:`processors/video` processor template for youtube videos
+- Modify :doc:`processors/boxed-text` processor to have optional type parameter
+- Update style error message to inclue line numbers
+- Dependency updates:
+
+  - Update ``python-slugify`` to 1.2.5.
+  - Update ``setuptools`` to 39.1.0.
+  - Update ``sphinx`` to 1.6.6.
+  - Update ``sphinx_rtx_theme`` to 0.3.0.
+
 0.7.3
 =======================================
 

docs/source/processors/interactive.rst

@@ -18,13 +18,14 @@ interactive as requested.
 
 You can include an interactive using the following text tag:
 
-.. literalinclude:: ../../../verto/tests/assets/interactive/doc_example_in_page_usage.md
+.. literalinclude:: ../../../verto/tests/assets/interactive-tag/doc_example_in_page_usage.md
     :language: none
 
 Required Tag Parameters
 ***************************************
 
-- ``name`` - The name to the interactive to include/link to.
+- ``slug`` - The slug to the interactive to include/link to.
+  This slug is added to the list of interactives in ``required_files``.
 - ``type`` - Sets the way the interactive is included in the page. Must be set
   to one of the following values:
 
@@ -33,27 +34,33 @@ Required Tag Parameters
       page).
     - ``whole-page`` - Creates a link to the interactive displayed on a
       separate page (this is the preferred method for including an interactive
-      on a separate page). The link shows a thumbnail of the interactive with
-      text (the text is set using the ``text`` parameter).
+      on a separate page).
+      The link shows a thumbnail of the interactive with text (the text is set using the
+      ``text`` parameter).
       By default, the thumbnail should be a ``thumbnail.png`` file found
       within the interactive's img folder.
     - ``iframe`` - The interactive is included in the page by embedding using
-      an iframe. This is used if the interactive is included multiple times on
+      an iframe.
+      This is used if the interactive is included multiple times on
       the page to avoid conflicts in JavaScript/CSS.
 
 Optional Tag Parameters
 ***************************************
 
-- ``text`` (used with ``whole-page`` value) - Sets the text for the interactive
-  link. If no text is given, the link uses the text ``Click to load
-  {{ name }}``.
+- ``text`` - Boolean flag to indicate whether the interactive has custom text to dispaly.
+
+    -  If given as ``true``, the the subtitle is the first block of text with the interactive block.
+    -  This is only use with the ``whole-page`` value.
+    -  If no text is given, the link uses the text ``Click to load {{ slug }}``.
+
 - ``parameters`` (used with ``whole-page`` and ``iframe`` values) - Adds the parameters
-  to interactive link. For example: ``digits=5&start=BBBBB``. Do not include
-  the ``?`` at the start, as this is already included in the output.
+  to interactive link. 
+  For example: ``digits=5&start=BBBBB``.
+  Do not include the ``?`` at the start, as this is already included in the output.
 - ``thumbnail`` (optional - used with ``whole-page`` value) - Displays an
   alternative thumbnail for the interactive. When not provided, it defaults to
-  ``interactives/interactive-name/img/thumbnail.png``, where ``interactive-name`` is the
-  value given for the ``name`` tag parameter (see above).
+  ``interactives/interactive-slug/img/thumbnail.png``, where ``interactive-slug`` is the
+  value given for the ``slug`` tag parameter (see above).
 
   - If the ``thumbnail`` value provided is a relative link (a link that
     doesn't start with ``http:``), the link will be rendered with a Django
@@ -86,36 +93,36 @@ Examples
 
 Using the following example tag:
 
-.. literalinclude:: ../../../verto/tests/assets/interactive/doc_example_in_page_usage.md
+.. literalinclude:: ../../../verto/tests/assets/interactive-tag/doc_example_in_page_usage.md
     :language: none
 
 The resulting HTML would be:
 
-.. literalinclude:: ../../../verto/tests/assets/interactive/doc_example_in_page_usage_expected.html
+.. literalinclude:: ../../../verto/tests/assets/interactive-tag/doc_example_in_page_usage_expected.html
     :language: html
 
 **whole-page example**
 
 Using the following example tag:
 
-.. literalinclude:: ../../../verto/tests/assets/interactive/doc_example_whole_page_usage.md
+.. literalinclude:: ../../../verto/tests/assets/interactive-container/doc_example_whole_page_usage.md
     :language: none
 
 The resulting HTML would be:
 
-.. literalinclude:: ../../../verto/tests/assets/interactive/doc_example_whole_page_usage_expected.html
+.. literalinclude:: ../../../verto/tests/assets/interactive-container/doc_example_whole_page_usage_expected.html
     :language: html
 
 **iframe example**
 
 Using the following example tag:
 
-.. literalinclude:: ../../../verto/tests/assets/interactive/doc_example_iframe_usage.md
+.. literalinclude:: ../../../verto/tests/assets/interactive-tag/doc_example_iframe_usage.md
     :language: none
 
 The resulting HTML would be:
 
-.. literalinclude:: ../../../verto/tests/assets/interactive/doc_example_iframe_usage_expected.html
+.. literalinclude:: ../../../verto/tests/assets/interactive-tag/doc_example_iframe_usage_expected.html
     :language: html
 
 Overriding HTML for Interactives
@@ -124,7 +131,7 @@ Overriding HTML for Interactives
 When overriding the HTML for interactives, the following Jinja2 placeholders are available:
 
 - ``{{ type }}`` - The type of the interactive.
-- ``{{ name }}`` - The slug name of the interactive to include/link to.
+- ``{{ slug }}`` - The slug of the interactive to include/link to.
 - ``{{ text }}`` - The text to to display to a link to a ``whole-page``
   interactive.
 - ``{{ parameters }}`` - GET parameters to append to the interactive link.
@@ -138,17 +145,17 @@ thumbnail.
 
 For example, providing the following HTML:
 
-.. literalinclude:: ../../../verto/tests/assets/interactive/doc_example_override_html_template.html
+.. literalinclude:: ../../../verto/tests/assets/interactive-container/doc_example_override_html_template.html
    :language: css+jinja
 
 with the following tag:
 
-.. literalinclude:: ../../../verto/tests/assets/interactive/doc_example_override_html.md
+.. literalinclude:: ../../../verto/tests/assets/interactive-container/doc_example_override_html.md
    :language: none
 
 would result in:
 
-.. literalinclude:: ../../../verto/tests/assets/interactive/doc_example_override_html_expected.html
+.. literalinclude:: ../../../verto/tests/assets/interactive-container/doc_example_override_html_expected.html
    :language: html
 
 

docs/source/usage.rst

@@ -51,6 +51,19 @@ Once the module is imported, you can create a Verto converter creating an Verto
 
 - ``extensions`` -  A list of extra Markdown extensions to run in the converter. Details on how to use this parameter can be found on the :doc:`extensions` page.
 
+- ``custom_argument_rules`` - A dictionary to modify the default argument rules for each tag. The default rules can found by reading the documentation for each tag.
+
+  - *For example:* By default, the ``image-inline`` tag requires alt text to be given, to change this, the following custom argument rules file would be used:
+
+    .. code-block:: python
+
+      {
+        "image-inline": {
+          "alt": false
+        }
+      }
+
+
 Step 3: Convert Markdown with converter
 =======================================
 

requirements.txt

@@ -1,9 +1,9 @@
 # Required dependencies for Verto (installed automatically in setup.py)
 markdown==2.6.11
 Jinja2==2.10
-python-slugify==1.2.4
-setuptools==38.4.0
+python-slugify==1.2.5
+setuptools==40.2.0
 
 # Required dependencies for building documentation
-sphinx==1.6.6
-sphinx_rtd_theme==0.2.4
+sphinx==1.7.7
+sphinx_rtd_theme==0.4.1

verto/Verto.py

@@ -13,7 +13,8 @@
     'image-container',
     'image-tag',
     'image-inline',
-    'interactive',
+    'interactive-tag',
+    'interactive-container',
     'panel',
     'relative-link',
     'save-title',
@@ -29,7 +30,7 @@ class Verto(object):
     to HTML.
     '''
 
-    def __init__(self, processors=DEFAULT_PROCESSORS, html_templates={}, extensions=[]):
+    def __init__(self, processors=DEFAULT_PROCESSORS, html_templates={}, extensions=[], custom_argument_rules={}):
         '''Creates a Verto object.
 
         Args:
@@ -43,18 +44,22 @@ def __init__(self, processors=DEFAULT_PROCESSORS, html_templates={}, extensions=
                 eg: {'image': '<img src={{ source }}>'}
             extensions: A list of extra extensions to run on the
                 markdown package.
+            custom_argument_rules: A dictionary of rules for the processors to
+                override default processor rules.
         '''
         self.processors = set(processors)
         self.html_templates = dict(html_templates)
         self.extensions = list(extensions)
+        self.custom_argument_rules = custom_argument_rules
         self.create_converter()
 
     def create_converter(self):
         '''Create the Verto extension and converter for future use.'''
         self.verto_extension = VertoExtension(
             processors=self.processors,
             html_templates=self.html_templates,
-            extensions=self.extensions
+            extensions=self.extensions,
+            custom_argument_rules=self.custom_argument_rules,
         )
         all_extensions = self.extensions + [self.verto_extension]
         self.converter = markdown.Markdown(extensions=all_extensions)

verto/VertoExtension.py

@@ -6,7 +6,8 @@
 from verto.processors.ImageInlinePattern import ImageInlinePattern
 from verto.processors.ImageTagBlockProcessor import ImageTagBlockProcessor
 from verto.processors.ImageContainerBlockProcessor import ImageContainerBlockProcessor
-from verto.processors.InteractiveBlockProcessor import InteractiveBlockProcessor
+from verto.processors.InteractiveTagBlockProcessor import InteractiveTagBlockProcessor
+from verto.processors.InteractiveContainerBlockProcessor import InteractiveContainerBlockProcessor
 from verto.processors.RelativeLinkPattern import RelativeLinkPattern
 from verto.processors.RemoveTitlePreprocessor import RemoveTitlePreprocessor
 from verto.processors.SaveTitlePreprocessor import SaveTitlePreprocessor
@@ -30,6 +31,8 @@
 from verto.utils.overrides import OListProcessor
 from verto.utils.overrides import UListProcessor
 
+from verto.errors.CustomArgumentRulesError import CustomArgumentRulesError
+
 from collections import defaultdict, OrderedDict
 from os import listdir
 import os.path
@@ -46,7 +49,7 @@ class VertoExtension(Extension):
     the Verto converter.
     '''
 
-    def __init__(self, processors=[], html_templates={}, extensions=[], *args, **kwargs):
+    def __init__(self, processors=[], html_templates={}, extensions=[], custom_argument_rules={}, *args, **kwargs):
         '''
         Args:
             processors: A set of processor names given as strings for which
@@ -61,8 +64,9 @@ def __init__(self, processors=[], html_templates={}, extensions=[], *args, **kwa
         '''
         super().__init__(*args, **kwargs)
         self.jinja_templates = self.loadJinjaTemplates(html_templates)
-        self.processor_info = self.loadProcessorInfo()
         self.processors = processors
+        self.custom_argument_rules = custom_argument_rules
+        self.processor_info = self.loadProcessorInfo()
         self.title = None
         self.heading_tree = None
         self.custom_slugify = UniqueSlugify()
@@ -144,9 +148,9 @@ def loadJinjaTemplates(self, custom_templates):
         '''
         templates = {}
         env = Environment(
-                loader=PackageLoader('verto', 'html-templates'),
-                autoescape=select_autoescape(['html'])
-                )
+            loader=PackageLoader('verto', 'html-templates'),
+            autoescape=select_autoescape(['html'])
+        )
         for file in listdir(os.path.join(os.path.dirname(__file__), 'html-templates')):
             html_file = re.search(r'(.*?).html$', file)
             if html_file:
@@ -174,7 +178,8 @@ def buildProcessors(self, md, md_globals):
             # Markdown overrides
             ['heading', HeadingBlockProcessor(self, md.parser), '<hashheader'],
             # Single line (in increasing complexity)
-            ['interactive', InteractiveBlockProcessor(self, md.parser), '<paragraph'],
+            ['interactive-tag', InteractiveTagBlockProcessor(self, md.parser), '<paragraph'],
+            ['interactive-container', InteractiveContainerBlockProcessor(self, md.parser), '<paragraph'],
             ['image-container', ImageContainerBlockProcessor(self, md.parser), '<paragraph'],
             ['image-tag', ImageTagBlockProcessor(self, md.parser), '<paragraph'],
             ['video', VideoBlockProcessor(self, md.parser), '<paragraph'],
@@ -218,7 +223,10 @@ def loadProcessorInfo(self):
             The json object of the file where objects are ordered dictionaries.
         '''
         json_data = pkg_resources.resource_string('verto', 'processor-info.json').decode('utf-8')
-        return json.loads(json_data, object_pairs_hook=OrderedDict)
+        json_data = json.loads(json_data, object_pairs_hook=OrderedDict)
+        if len(self.custom_argument_rules) != 0:
+            self.modify_rules(json_data)
+        return json_data
 
     def get_heading_tree(self):
         '''
@@ -240,3 +248,26 @@ def _set_heading_tree(self, tree):
         assert isinstance(tree, tuple)
         assert all(isinstance(child, HeadingNode) for child in tree)
         self.heading_tree = tree
+
+    def modify_rules(self, json_data):
+        '''
+        Modify the default tag argument rules using given custom rules.
+
+        Args:
+            json_data: dictionary of rules for processors parsing tags
+        Return:
+            json_data: dictionary of rules for processors parsing tags,
+                with modified rules arcording to custom rules given.
+        '''
+        for processor, arguments_to_modify in self.custom_argument_rules.items():
+            if processor not in self.processors:
+                msg = '\'{}\' is not a valid processor.'.format(processor)
+                raise CustomArgumentRulesError(processor, msg)
+            for argument in arguments_to_modify.items():
+                new_required = argument[1]
+                try:
+                    json_data[processor]['arguments'][argument[0]]['required'] = new_required
+                except KeyError:
+                    msg = '\'{}\' is not a valid argument for the \'{}\' processor.'.format(argument[0], processor)
+                    raise CustomArgumentRulesError(argument[0], msg)
+        return json_data

verto/__init__.py

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

verto/errors/CustomArgumentRulesError.py

@@ -0,0 +1,17 @@
+from verto.errors.Error import Error
+
+
+class CustomArgumentRulesError(Error):
+    '''Exception raised when custom argument rules refer to a processors
+    that does not exist.
+
+    Attributes:
+        tag: tag which was not matched
+        argument: the argument that was not found
+        value: the value that was not matched
+        message: explanation of why error was thrown
+    '''
+
+    def __init__(self, argument, message):
+        super().__init__(message)
+        self.argument = argument

verto/errors/InteractiveMissingTextError.py

@@ -0,0 +1,16 @@
+from verto.errors.Error import Error
+
+
+class InteractiveMissingTextError(Error):
+    '''Exception raised when an interactve is missing text.
+
+    Attributes:
+        tag: tag which was not matched
+        argument: the argument that was not found
+    '''
+
+    def __init__(self, tag, argument):
+        self.tag = tag
+        self.argument = argument
+        self.message = '\'text\' is \'true\' but not supplied.'
+        super().__init__(self.message)