Merge branch 'release/0.11.0'

docs/source/changelog.rst

@@ -1,12 +1,25 @@
 Changelog
 #######################################
 
+0.11.0
+=======================================
+
+- Replaces ``custom_argument_rules`` configuration parameter with ``settings`` parameter. The ``custom_argument_rules`` parameter is now set within ``settings`` under a new name. The settings also allow configuring if thumbnail images for interactives are added to the required images set. More information on these settings can be found in the :doc:`usage` documentation.
+- Improve documentation on how to create a release.
+- Dependency updates:
+
+  - Update ``setuptools`` from 40.4.3 to 41.0.1
+  - Update ``sphinx_rtd_theme`` from 0.4.1 to 0.4.3.
+  - Update ``coverage`` from 4.5.1 to 4.5.3.
+  - Update ``Jinja2`` from 2.10 to 2.10.1.
+  - Update ``python-slugify`` from 1.2.6 to 3.0.2.
+
 0.10.0
 =======================================
 
 - Add title parameter to :doc:`processors/video` processor for translations.
 - Dependency updates:
-  
+
   - Update ``setuptools`` to 40.4.3
   - Update ``sphinx`` to 1.8.1
 

docs/source/contributing.rst

@@ -381,15 +381,52 @@ Creating a release
 =======================================
 
 This is our current process for creating and publishing a Verto release. This
-can only be performed by repository administrators
+can only be performed by repository administrators.
 
 1. `Create a release branch`_. Checkout to this branch.
+
+  .. code-block:: bash
+
+    $ git checkout develop
+    $ git pull
+    $ git checkout -b release/0.7.0
+
 2. Update the version number [1]_ within ``verto/__init__.py``.
 3. Check test suite for errors, and fix any issues that arise, or `log an issue`_.
 4. Detail the changes in ``docs/source/changelog.rst``.
 5. `Complete the release branch`_. Be sure to tag the release with the version number for creating the release on GitHub.
-6. Create the release on `GitHub`_ on the tagged commit.
-7. Upload a new version of Verto to PyPI.
+
+  .. code-block:: bash
+
+    $ git checkout master
+    $ git pull 
+    $ git merge --no-ff release/0.7.0
+    $ git tag -a 0.7.0
+    $ git push
+    $ git push --tags
+
+
+6. `Upload the release to PyPI`_
+
+  .. code-block:: bash
+
+    $ rm -r dist/
+    $ python3 -m pip install --user --upgrade setuptools wheel
+    $ python3 setup.py sdist bdist_wheel
+    $ python3 -m pip install --user --upgrade twine
+    $ twine upload dist/*
+
+7. Merge the release into develop
+
+  .. code-block:: bash
+
+    $ git checkout develop
+    $ git pull
+    $ git merge --no-ff release/0.7.0
+
+8. Create the release on `GitHub`_ on the tagged commit.
+9. Delete the release branch.
+
 
 Other notes
 =======================================
@@ -418,4 +455,5 @@ However pinning dependencies ensure we control over each Verto release, followin
 .. _Create a release branch: http://nvie.com/posts/a-successful-git-branching-model/#creating-a-release-branch
 .. _log an issue: https://github.com/uccser/cs-field-guide/issues/new
 .. _Complete the release branch: http://nvie.com/posts/a-successful-git-branching-model/#finishing-a-release-branch
+.. _Upload the release to PyPI: https://packaging.python.org/tutorials/packaging-projects/
 .. _GitHub: https://github.com/uccser/verto/releases/

docs/source/usage.rst

@@ -51,37 +51,43 @@ 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.
+- ``settings`` - A dictionary of settings to override default Verto settings. The following settings are available:
 
-  - *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:
+  - ``add_default_interactive_thumbnails_to_required_files`` - Boolean stating whether default interactive thumbnail filepaths should be added to the required files set of images. Default is ``True``.
 
-    .. code-block:: python
+  - ``add_custom_interactive_thumbnails_to_required_files`` - Boolean stating whether custom interactive thumbnail filepaths provided as tag arguments should be added to the required files set of images. External images are never added. Default is ``True``.
+
+  - ``processor_argument_overrides`` - 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 would be used:
+
+      .. code-block:: python
 
-      {
-        "image-inline": {
-          "alt": False
+        {
+          "image-inline": {
+            "alt": False
+          }
         }
-      }
 
- .. warning::
+  .. 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:
+    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
+    .. code-block:: python
 
-      {
-        "image-inline": {
-          "alt": False
-        },
-        "image-tag": {
-          "alt": False
-        },
-        "image-container": {
-          "alt": False
+        {
+          "image-inline": {
+            "alt": False
+          },
+          "image-tag": {
+            "alt": False
+          },
+          "image-container": {
+            "alt": False
+          }
         }
-      }
 
 
 Step 3: Convert Markdown with converter

requirements-dev.txt

@@ -1,5 +1,5 @@
-setuptools==40.4.3
+setuptools==41.0.1
 sphinx==1.8.1
-sphinx_rtd_theme==0.4.1
-coverage==4.5.1
+sphinx_rtd_theme==0.4.3
+coverage==4.5.3
 flake8==3.5.0

requirements.txt

@@ -1,3 +1,3 @@
 markdown==2.6.11
-Jinja2==2.10
-python-slugify==1.2.6
+Jinja2==2.10.1
+python-slugify==3.0.2

verto/Verto.py

@@ -31,7 +31,7 @@ class Verto(object):
     to HTML.
     '''
 
-    def __init__(self, processors=DEFAULT_PROCESSORS, html_templates={}, extensions=[], custom_argument_rules={}):
+    def __init__(self, processors=DEFAULT_PROCESSORS, html_templates={}, extensions=[], custom_settings={}):
         '''Creates a Verto object.
 
         Args:
@@ -45,13 +45,12 @@ 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.
+            custom_settings: A dictionary of settings to override default settings.
         '''
         self.processors = set(processors)
         self.html_templates = dict(html_templates)
         self.extensions = list(extensions)
-        self.custom_argument_rules = custom_argument_rules
+        self.custom_settings = custom_settings
         self.create_converter()
 
     def create_converter(self):
@@ -60,7 +59,7 @@ def create_converter(self):
             processors=self.processors,
             html_templates=self.html_templates,
             extensions=self.extensions,
-            custom_argument_rules=self.custom_argument_rules,
+            custom_settings=self.custom_settings,
         )
         all_extensions = self.extensions + [self.verto_extension]
         self.converter = markdown.Markdown(extensions=all_extensions)

verto/VertoExtension.py

@@ -50,7 +50,7 @@ class VertoExtension(Extension):
     the Verto converter.
     '''
 
-    def __init__(self, processors=[], html_templates={}, extensions=[], custom_argument_rules={}, *args, **kwargs):
+    def __init__(self, processors=[], html_templates={}, extensions=[], custom_settings={}, *args, **kwargs):
         '''
         Args:
             processors: A set of processor names given as strings for which
@@ -62,11 +62,12 @@ def __init__(self, processors=[], html_templates={}, extensions=[], custom_argum
                 as values.
                 eg: {'image': '<img src={{ source }}>'}
             extensions: A list of extra extensions for compatibility.
+            custom_settings: A dictionary of user settings to override defaults.
         '''
         super().__init__(*args, **kwargs)
         self.jinja_templates = self.loadJinjaTemplates(html_templates)
         self.processors = processors
-        self.custom_argument_rules = custom_argument_rules
+        self.settings = self.get_settings(custom_settings)
         self.processor_info = self.loadProcessorInfo()
         self.title = None
         self.heading_tree = None
@@ -226,7 +227,7 @@ def loadProcessorInfo(self):
         '''
         json_data = pkg_resources.resource_string('verto', 'processor-info.json').decode('utf-8')
         json_data = json.loads(json_data, object_pairs_hook=OrderedDict)
-        if len(self.custom_argument_rules) != 0:
+        if len(self.settings['processor_argument_overrides']) != 0:
             self.modify_rules(json_data)
         return json_data
 
@@ -261,7 +262,7 @@ def modify_rules(self, json_data):
             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():
+        for processor, arguments_to_modify in self.settings['processor_argument_overrides'].items():
             if processor not in self.processors:
                 msg = '\'{}\' is not a valid processor.'.format(processor)
                 raise CustomArgumentRulesError(processor, msg)
@@ -273,3 +274,22 @@ def modify_rules(self, json_data):
                     msg = '\'{}\' is not a valid argument for the \'{}\' processor.'.format(argument[0], processor)
                     raise CustomArgumentRulesError(argument[0], msg)
         return json_data
+
+    def get_settings(self, user_settings):
+        '''Return the settings for the Verto extension.
+
+        Any provided user settings override the default settings.
+
+        Args:
+            user_settings (dict): User overrides of settings.
+
+        Returns:
+            Dictionary of settings.
+        '''
+        settings = {
+            'add_default_interactive_thumbnails_to_required_files': True,
+            'add_custom_interactive_thumbnails_to_required_files': True,
+            'processor_argument_overrides': dict(),
+        }
+        settings.update(user_settings)
+        return settings

verto/__init__.py

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

verto/processors/GenericContainerBlockProcessor.py

@@ -15,6 +15,7 @@ def __init__(self, processor, ext, *args, **kwargs):
         '''
         super().__init__(*args, **kwargs)
         self.processor = processor
+        self.settings = ext.settings
         tag_argument = ext.processor_info[self.processor].get('tag_argument', self.processor)
         self.p_start = re.compile(r'(^|\n) *\{{{0} ?(?P<args>[^\}}]*)(?<! end)\}} *(\n|$)'.format(tag_argument))
         self.p_end = re.compile(r'(^|\n) *\{{{0} end\}} *(\n|$)'.format(tag_argument))

verto/processors/GenericTagBlockProcessor.py

@@ -15,6 +15,7 @@ def __init__(self, processor, ext, *args, **kwargs):
         '''
         super().__init__(*args, **kwargs)
         self.processor = processor
+        self.settings = ext.settings
         tag_argument = ext.processor_info[self.processor].get('tag_argument', self.processor)
         self.pattern = re.compile(r'(^|\n) *\{{{0} ?(?P<args>[^\}}]*)(?<! end)\}} *(\n|$)'.format(tag_argument))
         self.arguments = ext.processor_info[self.processor]['arguments']

verto/processors/InteractiveContainerBlockProcessor.py

@@ -4,6 +4,9 @@
 
 import re
 
+DEFAULT_THUMBNAIL = 'default'
+CUSTOM_THUMBNAIL = 'custom'
+
 
 class InteractiveContainerBlockProcessor(GenericContainerBlockProcessor):
     ''' Searches a Document for interactive tags e.g.
@@ -74,13 +77,19 @@ def custom_parsing(self, content_blocks, argument_values):
 
             if thumbnail_file_path is not None:
                 del argument_values[argument]
+                thumbnail_type = CUSTOM_THUMBNAIL
             else:
                 thumbnail_file_path = 'interactives/{}/img/thumbnail.png'.format(slug)
+                thumbnail_type = DEFAULT_THUMBNAIL
 
             external_path_match = re.search(r'^http', thumbnail_file_path)
             if external_path_match is None:  # internal image
                 thumbnail_file_relative = True
-                self.required_images.add(thumbnail_file_path)
+                add_default = self.settings['add_default_interactive_thumbnails_to_required_files']
+                add_custom = self.settings['add_custom_interactive_thumbnails_to_required_files']
+                if (thumbnail_type == DEFAULT_THUMBNAIL and add_default) or \
+                   (thumbnail_type == CUSTOM_THUMBNAIL and add_custom):
+                    self.required_images.add(thumbnail_file_path)
             else:
                 thumbnail_file_relative = False
 

verto/processors/InteractiveTagBlockProcessor.py

@@ -1,6 +1,9 @@
 from verto.processors.GenericTagBlockProcessor import GenericTagBlockProcessor
 import re
 
+DEFAULT_THUMBNAIL = 'default'
+CUSTOM_THUMBNAIL = 'custom'
+
 
 class InteractiveTagBlockProcessor(GenericTagBlockProcessor):
     '''Searches a Document for interactive tags:
@@ -56,13 +59,19 @@ def custom_parsing(self, argument_values):
 
             if thumbnail_file_path is not None:
                 del argument_values[argument]
+                thumbnail_type = CUSTOM_THUMBNAIL
             else:
                 thumbnail_file_path = 'interactives/{}/img/thumbnail.png'.format(slug)
+                thumbnail_type = DEFAULT_THUMBNAIL
 
             external_path_match = re.search(r'^http', thumbnail_file_path)
             if external_path_match is None:  # internal image
                 thumbnail_file_relative = True
-                self.required_images.add(thumbnail_file_path)
+                add_default = self.settings['add_default_interactive_thumbnails_to_required_files']
+                add_custom = self.settings['add_custom_interactive_thumbnails_to_required_files']
+                if (thumbnail_type == DEFAULT_THUMBNAIL and add_default) or \
+                   (thumbnail_type == CUSTOM_THUMBNAIL and add_custom):
+                    self.required_images.add(thumbnail_file_path)
             else:
                 thumbnail_file_relative = False