Merge branch 'release/0.9.0'

.coveragerc

@@ -0,0 +1,7 @@
+[run]
+branch = True
+source =
+    verto
+omit =
+    # Omit test files
+    */tests/*

.travis.yml

@@ -16,6 +16,11 @@ install:
 script:
   - flake8
   - python -m verto.tests.start_tests --travis
+  - coverage run --rcfile=.coveragerc -m verto.tests.start_tests --travis
+after_success:
+  - coverage xml -i
+  - coverage report -m --skip-covered
+  - bash <(curl -s https://codecov.io/bash)
 
 # Stop email notifications but post to organisation Slack channel
 notifications:

docs/source/changelog.rst

@@ -1,6 +1,16 @@
 Changelog
 #######################################
 
+0.9.0
+=======================================
+
+- Add :doc:`processors/blockquote` processor for customising block quote style.
+- Added CodeCov to repo
+- Dependency updates:
+
+  - Update ``python-slugify`` to 1.2.6
+  - Update ``sphinx`` to 1.8.0
+
 0.8.0
 =======================================
 

docs/source/processors/blockquote.rst

@@ -0,0 +1,62 @@
+Blockquote
+#######################################
+
+**Processor name:** ``blockquote``
+
+You can include an blockquote using the following text tag:
+
+.. literalinclude:: ../../../verto/tests/assets/blockquote/doc_example_basic_usage.md
+    :language: none
+
+Optional Tag Parameters
+***************************************
+
+- ``footer`` - Boolean flag to indicate whether the blockquote contains a footer.
+
+    - If given as ``true``, then the last line should start with ``- `` to show it's the footer.
+
+- ``source`` - Sets the ``cite`` parameter of the ``blockquote`` element.
+
+- ``alignment`` - Valid values are 'left', 'center', or 'right'. Providing one of these values Will add CSS classes to the image for alignment.
+
+The default HTML for a panel is:
+
+.. literalinclude:: ../../../verto/html-templates/blockquote.html
+   :language: css+jinja
+
+Using the following example tag:
+
+.. literalinclude:: ../../../verto/tests/assets/blockquote/doc_example_basic_usage.md
+   :language: none
+
+The resulting HTML would be:
+
+.. literalinclude:: ../../../verto/tests/assets/blockquote/doc_example_basic_usage_expected.html
+   :language: html
+
+Overriding HTML for Blockquote
+***************************************
+
+When overriding the HTML for blockquotes, the following Jinja2 placeholders are available:
+
+- ``{{ content }}`` - The text enclosed by the blockquote tags.
+- ``{{ footer }}`` - The provided footer text.
+- ``{{ alignment }}`` - The location to add extra CSS classes for alignment.
+- ``{{ source }}`` - The URL for the source.
+
+**Example**
+
+For example, providing the following HTML:
+
+.. literalinclude:: ../../../verto/tests/assets/blockquote/doc_example_override_html_template.html
+  :language: css+jinja
+
+with the following tag:
+
+.. literalinclude:: ../../../verto/tests/assets/blockquote/doc_example_override_html.md
+  :language: none
+
+would result in:
+
+.. literalinclude:: ../../../verto/tests/assets/blockquote/doc_example_override_html_expected.html
+  :language: html

docs/source/processors/image-inline.rst

@@ -1,7 +1,7 @@
 Inline Image
 #######################################
 
-**Processor name:** ``image-inline``
+**Processor name:** ``image-inline`` (see also :doc:`image`)
 
 .. note::
 

docs/source/processors/image.rst

@@ -1,7 +1,7 @@
 Image
 #######################################
 
-**Processor name:** ``image-tag`` and ``image-container``
+**Processor name:** ``image-tag`` and ``image-container`` (see also :doc:`image-inline`)
 
 You can include an image using the following text tag:
 
@@ -42,7 +42,7 @@ Optional Tag Parameters
 
 - ``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.
+- ``source`` - Adds the text 'Source' under the image with a link to the given source URL. Displays after the caption if a caption is given.
 
 - ``alignment`` - Valid values are 'left', 'center', or 'right'. Providing one of these values Will add CSS classes to the image for alignment.
 
@@ -73,8 +73,8 @@ When overriding the HTML for images, the following Jinja2 placeholders are avail
 - ``{{ 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>`_).
 - ``{{ alignment }}`` - The location to add extra CSS classes for alignment.
 - ``{{ caption }}`` - The text for the image caption.
-- ``{{ caption_link }}`` - The URL for the caption link .
-- ``{{ source_link }}`` - The URL for the source .
+- ``{{ caption_link }}`` - The URL for the caption link.
+- ``{{ source_link }}`` - The URL for the source.
 - ``{{ file_relative }}`` - If the ``full_file_path`` is a relative link, this is the boolean value ``True``, otherwise ``False``.
 
     If ``{{ file_relative }}`` is ``True``, the following placeholders are also available to allow finer control of output of relative images (see *Example 2* below):

docs/source/processors/index.rst

@@ -13,6 +13,7 @@ The following pages covers how to use the available processors within Markdown t
 .. toctree::
     :maxdepth: 1
 
+    blockquote
     boxed-text
     button-link
     comment

docs/source/processors/panel.rst

@@ -49,7 +49,7 @@ The resulting HTML would be:
 Overriding HTML for Panels
 ***************************************
 
-When overriding the HTML for images, the following Jinja2 placeholders are available:
+When overriding the HTML for panels, the following Jinja2 placeholders are available:
 
 - ``{{ type }}`` - The type of panel to be created.
 - ``{{ expanded }}`` - Text either set to 'true' or 'always' to state if the panel should be expanded. See parameter description above.

docs/source/usage.rst

@@ -53,13 +53,33 @@ Once the module is imported, you can create a Verto converter creating an Verto
 
 - ``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:
+  - *For example:* By default, the ``image-inline`` tag requires alt text to be given, to change this, the following custom argument rules would be used:
 
     .. code-block:: python
 
       {
         "image-inline": {
-          "alt": false
+          "alt": False
+        }
+      }
+
+ .. warning::
+
+   Some tags have multiple processors behind them (for example, the ``image-inline``, ``image-container`` and ``image-tag`` processors are all used for images).
+   This means that if you would like to change the default rules of one or more of their arguments, this will need to be done for each of the processors
+   individually. For example, to set the ``alt`` argument as ``False`` for all images, the custom argument rules would look as follows:
+
+   .. code-block:: python
+
+      {
+        "image-inline": {
+          "alt": False
+        },
+        "image-tag": {
+          "alt": False
+        },
+        "image-container": {
+          "alt": False
         }
       }
 

requirements.txt

@@ -1,9 +1,12 @@
 # Required dependencies for Verto (installed automatically in setup.py)
 markdown==2.6.11
 Jinja2==2.10
-python-slugify==1.2.5
+python-slugify==1.2.6
 setuptools==40.2.0
 
 # Required dependencies for building documentation
-sphinx==1.7.7
+sphinx==1.8.0
 sphinx_rtd_theme==0.4.1
+
+# Coverage Tools
+coverage==4.5.1

verto/Verto.py

@@ -2,6 +2,7 @@
 from verto.VertoExtension import VertoExtension
 
 DEFAULT_PROCESSORS = frozenset({
+    'blockquote',
     'boxed-text',
     'button-link',
     'comment',

verto/VertoExtension.py

@@ -2,6 +2,7 @@
 import markdown.util as utils
 
 from verto.processors.CommentPreprocessor import CommentPreprocessor
+from verto.processors.BlockquoteBlockProcessor import BlockquoteBlockProcessor
 from verto.processors.VideoBlockProcessor import VideoBlockProcessor
 from verto.processors.ImageInlinePattern import ImageInlinePattern
 from verto.processors.ImageTagBlockProcessor import ImageTagBlockProcessor
@@ -185,6 +186,7 @@ def buildProcessors(self, md, md_globals):
             ['video', VideoBlockProcessor(self, md.parser), '<paragraph'],
             ['conditional', ConditionalProcessor(self, md.parser), '<paragraph'],
             ['panel', PanelBlockProcessor(self, md.parser), '<paragraph'],
+            ['blockquote', BlockquoteBlockProcessor(self, md.parser), '<paragraph'],
             # Multiline
         ]
         self.inlinepatterns = [  # A special treeprocessor

verto/__init__.py

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

verto/errors/BlockquoteMissingFooterError.py

@@ -0,0 +1,17 @@
+from verto.errors.Error import Error
+
+
+class BlockquoteMissingFooterError(Error):
+    '''Exception raised when a blockquote is missing a footer when argument is given.
+
+    Attributes:
+        tag: tag which was not matched
+        block: block where tag was not matched
+        argument: the argument that was not found
+    '''
+
+    def __init__(self, tag, argument):
+        self.tag = tag
+        self.argument = argument
+        self.message = '\'footer\' is \'true\' but not supplied.'
+        super().__init__(self.message)

verto/html-templates/blockquote.html

@@ -0,0 +1,11 @@
+<blockquote class="blockquote{% if alignment == 'left' %} text-left{% elif alignment =='center' %} text-center{% elif alignment =='right' %} text-right{% endif %}"
+{%- if source %} cite="{{ source }}"{% endif %}>
+{% autoescape false -%}
+{{ content }}
+{%- endautoescape -%}
+{% if footer %}
+<footer class="blockquote-footer">
+{{ footer }}
+</footer>
+{% endif %}
+</blockquote>

verto/processor-info.json

@@ -1,4 +1,36 @@
 {
+    "blockquote": {
+        "class": "custom",
+        "arguments": {
+          "alignment": {
+            "required": false,
+            "dependencies": [],
+            "values": ["left", "center", "right"]
+          },
+          "source": {
+            "required": false,
+            "dependencies": []
+          },
+          "footer": {
+            "required": false,
+            "values": ["true", "false"]
+          }
+        },
+        "template_parameters": {
+          "content": {
+            "argument": "content"
+          },
+          "footer": {
+            "argument": "footer"
+          },
+          "alignment": {
+            "argument": "alignment"
+          },
+          "source": {
+            "argument": "source"
+          }
+        }
+    },
     "boxed-text": {
         "class": "generic_container",
         "arguments": {

verto/processors/BlockquoteBlockProcessor.py

@@ -0,0 +1,45 @@
+from verto.processors.GenericContainerBlockProcessor import GenericContainerBlockProcessor
+from verto.errors.BlockquoteMissingFooterError import BlockquoteMissingFooterError
+
+BLOCKQUOTE_FOOTER_PREFIX = "- "
+
+
+class BlockquoteBlockProcessor(GenericContainerBlockProcessor):
+    def __init__(self, *args, **kwargs):
+        '''
+        Args:
+            ext: An instance of the Verto Extension.
+        '''
+        self.processor = 'blockquote'
+        super().__init__(self.processor, *args, **kwargs)
+
+    def custom_parsing(self, content_blocks, argument_values):
+        '''
+        Extracts the footer of a blockquote if provided.
+
+        Args:
+            content_blocks (list): Strings to either be parsed or inserted
+                                   as content in template.
+            argument_values (dict): Dictionary of values to be inserted in template.
+
+        Returns:
+            Tuple containing blocks and extra_args to update the content_blocks list and argument_values dict.
+        '''
+        extra_args = {}
+        blocks = content_blocks
+
+        argument = 'footer'
+        if argument_values.get(argument) == 'true':
+            footer_index = -2
+            if content_blocks[footer_index].startswith(BLOCKQUOTE_FOOTER_PREFIX):
+                footer = content_blocks[footer_index]
+                footer = footer[len(BLOCKQUOTE_FOOTER_PREFIX):]
+                extra_args[argument] = footer
+                blocks = content_blocks[:footer_index]
+            else:
+                raise BlockquoteMissingFooterError(self.processor, argument)
+        elif argument_values.get(argument) == 'false':
+            # delete from argument dict so as to not be included in template
+            del argument_values[argument]
+
+        return (blocks, extra_args)