Merge branch 'issue/56' into develop (fixes #56)

uccser · Feb 14, 2017 · 31610df · 31610df
2 parents 82c5f77 + 0883a03
commit 31610df
Show file tree

Hide file tree

Showing 36 changed files with 152 additions and 187 deletions.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -24,41 +24,11 @@ For example:
 
     install
     usage
-    tags/index
+    processors/index
     extensions
 
-Available Tags
-==============
-
-The following tags are directly converted to HTML:
-
-- **Images:** Includes an image, with additional parameters for alternative text, wrapping, captions, and source links. Kordac also remembers all images that have found within image tags, which is useful for later checking if all files exist.
-- **Videos:** Embeds a YouTube or Vimeo video from a given URL.
-- **Text boxes:** Wraps the given content within a block that can be styled by CSS.
-- **Panels:** Wraps the given content in a container with an optional header. Panels can be collapsed by JS, and a parameter allows the panel to be collapsed or expanded on page load.
-
-The following tags convert to placeholders to be used by the Django template engine:
-
-- **Static file links:** When linking to a specific static file, this tag will prepend a placeholder for the Django static files path.
-- **Numbered Headings:**
-- **Interactives:**
-- **Table of contents:**
-- **Conditional content:**
-
-Kordac also includes the following tags
-
-- **Glossary Entries:**
-- **Comments:**
-
 Other Features
 ==============
 
-- HTML for any given tag can replaced
-- Specific tags can be enabled while ignoring all other tags
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+- HTML for any given processor can replaced
+- Specific processors can be enabled while ignoring all other processors
diff --git a/docs/source/tags/boxed-text.rst → docs/source/processors/boxed-text.rst b/docs/source/tags/boxed-text.rst → docs/source/processors/boxed-text.rst
@@ -1,9 +1,9 @@
 Boxed Text
 #######################################
 
-**Tag name:** ``boxed-text``
+**Processor name:** ``boxed-text``
 
-You can enclose text inside of a box using the following syntax:
+You can enclose text inside of a box using the following text tag:
 
 .. literalinclude:: ../../../tests/assets/boxed-text/doc_example_basic_usage.md
    :language: none

diff --git a/docs/source/tags/button-link.rst → docs/source/processors/button-link.rst b/docs/source/tags/button-link.rst → docs/source/processors/button-link.rst
@@ -1,9 +1,9 @@
 Button Link
 #######################################
 
-**Tag name:** ``button-link``
+**Processor name:** ``button-link``
 
-You can create a link on a button using the following syntax:
+You can create a link on a button using the following text tag:
 
 .. literalinclude:: ../../../tests/assets/button-link/doc_example_basic_usage.md
    :language: none

diff --git a/docs/source/tags/comment.rst → docs/source/processors/comment.rst b/docs/source/tags/comment.rst → docs/source/processors/comment.rst
@@ -1,7 +1,7 @@
 Comment
 #######################################
 
-**Tag name:** ``comment``
+**Processor name:** ``comment``
 
 You can include comments in the source text that are deleted before conversion:
 

diff --git a/docs/source/tags/image.rst → docs/source/processors/image.rst b/docs/source/tags/image.rst → docs/source/processors/image.rst
@@ -1,9 +1,9 @@
 Image
 #######################################
 
-**Tag name:** ``image``
+**Processor name:** ``image``
 
-You can include an image using the following syntax:
+You can include an image using the following text tag:
 
 .. code-block:: none
 

diff --git a/docs/source/processors/index.rst b/docs/source/processors/index.rst
@@ -0,0 +1,22 @@
+Using Processors
+#######################################
+
+- Tags should always be separated with newlines before and after each tag.
+- If a processor requires both a start and end tag (for example: panels) and one tag is missing then a ``TagNotMatchedError`` Exception will be thrown.
+
+Available Processors
+#######################################
+
+The following pages covers how to use the available processors within Markdown text:
+
+.. toctree::
+    :maxdepth: 1
+
+    boxed-text
+    button-link
+    comment
+    image
+    internal-text-links
+    panel
+    remove-title
+    save-title
diff --git a/docs/source/tags/internal-text-links.rst → ...source/processors/internal-text-links.rst b/docs/source/tags/internal-text-links.rst → ...source/processors/internal-text-links.rst
@@ -1,7 +1,7 @@
 Internal Text Links
 #######################################
 
-**Tag name:** ``internal-text-links``
+**Processor name:** ``internal-text-links``
 
 This processor will find any internal text links (a link that doesn't start with ``http:``), and prepend the link with a Django template placeholder.
 When the resulting HTML is rendered with Django, the Django system can insert the root URL into the template placeholder for correct rendering.

diff --git a/docs/source/tags/panel.rst → docs/source/processors/panel.rst b/docs/source/tags/panel.rst → docs/source/processors/panel.rst
@@ -1,9 +1,9 @@
 Panel
 #######################################
 
-**Tag name:** ``panel``
+**Processor name:** ``panel``
 
-You can include an panel using the following syntax:
+You can include an panel using the following text tag:
 
 .. literalinclude:: ../../../tests/assets/panel/doc_example_basic_usage.md
     :language: none

diff --git a/docs/source/tags/remove-title.rst → docs/source/processors/remove-title.rst b/docs/source/tags/remove-title.rst → docs/source/processors/remove-title.rst
@@ -1,14 +1,14 @@
 Remove Title
 #######################################
 
-**Tag name:** ``remove-title``
+**Processor name:** ``remove-title``
 
 This preprocessor runs before any conversion of Markdown and searches for the first heading in the provided Markdown text.
 This preprocessor runs after the ``save-title`` preprocessor if present.
 Once it finds a heading on a line, it deletes that line of text.
 
 This preprocessor is **not** turned on by default.
-To use ``remove-title``, it needs to be explicity provided in the ``tags`` parameter when creating the Kordac converter, or given in the ``update_tags`` method (see example below).
+To use ``remove-title``, it needs to be explicity provided in the ``processors`` parameter when creating the Kordac converter, or given in the ``update_processors`` method (see example below).
 
 **Example**
 

diff --git a/docs/source/tags/save-title.rst → docs/source/processors/save-title.rst b/docs/source/tags/save-title.rst → docs/source/processors/save-title.rst
diff --git a/docs/source/tags/index.rst b/docs/source/tags/index.rst
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -31,17 +31,17 @@ Once the module is imported, you can create a Kordac converter creating an Korda
 
 ``Kordac()`` has optional parameters to customise the converter. These are:
 
-- ``tags`` - A set of tag names given as strings for the converter to use. If this parameter is not given, the default tags are used. If ``tags`` is provided, all processors not listed are skipped.
+- ``processors`` - A set of processor names given as strings for the converter to use. If this parameter is not given, the default processors are used. If ``processors`` is provided, all processors not listed are skipped.
 
   - *For example:* Creating a Kordac converter that only deletes comment tags would be done by the following command:
 
     .. code-block:: python
 
-      converter = kordac.Kordac(tags={"comment"})
+      converter = kordac.Kordac(processors={"comment"})
 
-- ``html_templates`` - A dictionary of HTML templates to override existing HTML templates for tags. The dictionary contains tag names given as a string as keys mapping HTML strings as values.
+- ``html_templates`` - A dictionary of HTML templates to override existing HTML templates for processors. The dictionary contains processor names given as a string as keys mapping HTML strings as values.
 
-  The documentation page for each tag specificies how to create custom HTML for that tag.
+  The documentation page for each processor specificies how to create custom HTML for that processor.
 
   - *For example:* Creating a Kordac converter that uses  ``<img src={{ source }}>`` as custom HTML for ``image`` tags would be done by the following command:
 
@@ -84,35 +84,35 @@ The following attributes are available:
 Configuring Kordac converter after creation
 ===============================================
 
-The following functions allow you to change the tags or HTML templates used in conversion by the Kordac converter after its creation.
+The following functions allow you to change the processors or HTML templates used in conversion by the Kordac converter after its creation.
 
-Changing tags
+Changing processors
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. automethod:: kordac.Kordac.update_tags(tags)
+.. automethod:: kordac.Kordac.update_processors(processors)
 
-.. automethod:: kordac.Kordac.tag_defaults(tags)
+.. automethod:: kordac.Kordac.processor_defaults(processors)
 
-  This function is useful if you want to make minor changes to the default used tags. For example: with an existing Kordac converter ``converter``, you wish to still use all default tags but now skip video tags:
+  This function is useful if you want to make minor changes to the default used processors. For example: with an existing Kordac converter ``converter``, you wish to still use all default processors but now skip video tags:
 
   .. code-block:: python
 
-    tags = converter.tag_defaults()
-    tags.remove('video')
-    converter.update_tags(tags)
+    processors = converter.processor_defaults()
+    processors.remove('video')
+    converter.update_processors(processors)
 
 Changing HTML templates
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. automethod:: kordac.Kordac.update_templates(html_templates)
 
-.. automethod:: kordac.Kordac.default_templates(tags)
+.. automethod:: kordac.Kordac.default_templates()
 
 Full list of package methods
 =======================================
 
 .. autoclass:: kordac.Kordac()
-  :members: __init__, convert, update_tags, tag_defaults, update_templates, default_templates
+  :members: __init__, convert, update_processors, processor_defaults, update_templates, default_templates
 
 .. autoclass:: kordac.Kordac.KordacResult()
 
@@ -122,4 +122,4 @@ Full list of package methods
 
   .. attribute:: title
 
-    The text of the first heading found by the :doc:`tags/save-title` processor.
+    The text of the first heading found by the :doc:`processors/save-title` processor.
diff --git a/kordac/Kordac.py b/kordac/Kordac.py
@@ -1,7 +1,7 @@
 import markdown
 from kordac.KordacExtension import KordacExtension
 
-DEFAULT_TAGS = {
+DEFAULT_PROCESSORS = {
     'save-title',
     'heading',
     'comment',
@@ -15,33 +15,33 @@
 
 class Kordac(object):
     """A converter object for converting markdown
-    with complex tags to HTML.
+    with complex elements to HTML.
     """
 
-    def __init__(self, tags=DEFAULT_TAGS, html_templates={}, extensions=[]):
+    def __init__(self, processors=DEFAULT_PROCESSORS, html_templates={}, extensions=[]):
         """Creates a Kordac object.
 
         Args:
-            tags: A set of tag names given as strings for which
+            processors: A set of processor names given as strings for which
                 their processors are enabled. If given, all other
                 processors are skipped.
             html_templates: A dictionary of HTML templates to override
-                existing HTML templates for tags. Dictionary contains
-                tag names given as a string as keys mapping HTML strings
+                existing HTML templates for processors. Dictionary contains
+                processor names given as a string as keys mapping HTML strings
                 as values.
                 eg: {'image': '<img src={{ source }}>'}
             extensions: A list of extra extensions to run on the
                 markdown package.
         """
-        self.tags = tags
+        self.processors = processors
         self.html_templates = html_templates
         self.extensions = extensions
         self.create_converter()
 
     def create_converter(self):
         """Create the Kordac extension and converter for future use."""
         self.kordac_extension = KordacExtension(
-            tags=self.tags,
+            processors=self.processors,
             html_templates=self.html_templates
         )
         all_extensions = self.extensions + [self.kordac_extension]
@@ -73,8 +73,8 @@ def update_templates(self, html_templates):
 
         Args:
             html_templates: A dictionary of HTML templates to override
-                existing HTML templates for tags. Dictionary contains
-                tag names given as a string as keys mapping HTML strings
+                existing HTML templates for processors. Dictionary contains
+                processor names given as a string as keys mapping HTML strings
                 as values.
                 eg: {'image': '<img src={{ source }}>'}
         """
@@ -86,25 +86,25 @@ def default_templates(self):
         self.html_templates = {}
         self.create_converter()
 
-    def tag_defaults(self):
-        """Returns a copy of the default tag set.
+    def processor_defaults(self):
+        """Returns a copy of the default processor set.
 
         Returns:
-            A set of default tag names as strings.
+            A set of default processor names as strings.
         """
-        return DEFAULT_TAGS.copy()
+        return DEFAULT_PROCESSORS.copy()
 
-    def update_tags(self, tags=DEFAULT_TAGS):
-        """Update the tags used for conversion with the given set.
+    def update_processors(self, processors=DEFAULT_PROCESSORS):
+        """Update the processors used for conversion with the given set.
         The updated set will be used for converting from this point
-        onwards. If parameter is empty, default tags will be used.
+        onwards. If parameter is empty, default processors will be used.
 
         Args:
-            tags: A set of tag names given as strings for which
+            processors: A set of processor names given as strings for which
                 their processors are enabled. If given, all other
                 processors are skipped.
         """
-        self.tags = tags
+        self.processors = processors
         self.create_converter()
 
 class KordacResult(object):