Merge branch 'diegobz-master'

Author: cmacmackin

.gitignore

@@ -1,4 +1,3 @@
-*.rst
 *~
 markdown_include.egg-info/
 dist/

README.md

@@ -32,7 +32,19 @@ fragments present in the Markdown.
 By default, all file-names are evaluated relative to the location from which
 Markdown is being called. If you would like to change the directory relative to
 which paths are evaluated, then this can be done by specifying the extension
-setting ``base_dir``. 
+setting ``base_path``.
+
+
+```python
+import markdown
+from markdown_include.include import MarkdownInclude
+
+# Markdown Extensions
+markdown_include = MarkdownInclude(
+    configs={'base_path':'/srv/content/', 'encoding': 'iso-8859-1'}
+)
+html = markdown.markdown(source, extensions=[markdown_include])
+```
 
 ##ChangeLog
 ###Version 0.4

README.rst

@@ -0,0 +1,54 @@
+Markdown-Include
+================
+
+This is an extension to
+`Python-Markdown <https://pythonhosted.org/Markdown/>`__ which provides
+an "include" function, similar to that found in LaTeX (and also the C
+pre-processor and Fortran). I originally wrote it for my
+`FORD <https://pypi.python.org/pypi/FORD>`__ Fortran auto-documentation
+generator.
+
+Installation
+------------
+
+This module can now be installed using ``pip``.
+
+::
+
+    pip install markdown-include
+
+Usage
+-----
+
+This module can be used in a program in the following way:
+
+::
+
+    import markdown
+    html = markdown.markdown(source, extensions=[markdown_include.include'])
+
+The syntax for use within your Markdown files is ``{!filename!}``. This
+statement will be replaced by the contents of ``filename``.
+Markdown-Include will work recursively, so any included files within
+``filename`` wil also be included. This replacement is done prior to any
+other Markdown processing, so any Markdown syntax that you want can be used
+within your included files. Note that this is a change from the previous 
+version. It was felt that this syntax was less likely to conflict with any code
+fragments present in the Markdown.
+
+By default, all file-names are evaluated relative to the location from
+which Markdown is being called. If you would like to change the
+directory relative to which paths are evaluated, then this can be done
+by specifying the extension setting ``base_path``.
+
+::
+
+    import markdown
+    from markdown_include.include import MarkdownInclude
+
+    # Markdown Extensions
+    markdown_include = MarkdownInclude(
+        configs={'base_path':'/srv/content/', 'encoding': 'iso-8859-1'}
+    )
+    html = markdown.markdown(source, extensions=[markdown_include])
+

markdown_include/include.py

@@ -2,98 +2,102 @@
 # -*- coding: utf-8 -*-
 #
 #  include.py
-#  
+#
 #  Copyright 2015 Christopher MacMackin <cmacmackin@gmail.com>
-#  
+#
 #  This program is free software; you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
 #  the Free Software Foundation; either version 2 of the License, or
 #  (at your option) any later version.
-#  
+#
 #  This program is distributed in the hope that it will be useful,
 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 #  GNU General Public License for more details.
-#  
+#
 #  You should have received a copy of the GNU General Public License
 #  along with this program; if not, write to the Free Software
 #  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 #  MA 02110-1301, USA.
-#  
-#  
-
-
+#
+#
 
 from __future__ import print_function
-from markdown.extensions import Extension
-from markdown.preprocessors import Preprocessor
 import re
 import os.path
+from codecs import open
+from markdown.extensions import Extension
+from markdown.preprocessors import Preprocessor
 
 INC_SYNTAX = re.compile(r'\{!\s*(.+?)\s*!\}')
 
 
 class MarkdownInclude(Extension):
     def __init__(self, configs=[]):
-        self.config = {'base_path': ['.', 'Location from which to evaluate relative paths for the include statement.'],}
+        self.config = {
+            'base_path': ['.', 'Default location from which to evaluate ' \
+                'relative paths for the include statement.'],
+            'encoding': ['utf-8', 'Encoding of the files used by the include ' \
+                'statement.']
+        }
         for key, value in configs.items():
             self.setConfig(key, value)
-        
+
     def extendMarkdown(self, md, md_globals):
-        md.preprocessors.add('include', IncludePreprocessor(md,self.getConfigs()),'_begin')
-        
+        md.preprocessors.add(
+            'include', IncludePreprocessor(md,self.getConfigs()),'_begin'
+        )
 
 
 class IncludePreprocessor(Preprocessor):
     '''
     This provides an "include" function for Markdown, similar to that found in
-    LaTeX (also the C pre-processor and Fortran). The syntax is {{filename}},
+    LaTeX (also the C pre-processor and Fortran). The syntax is {!filename!},
     which will be replaced by the contents of filename. Any such statements in
     filename will also be replaced. This replacement is done prior to any other
     Markdown processing. All file-names are evaluated relative to the location
     from which Markdown is being called.
     '''
-    def __init__(self,md,config):
+    def __init__(self, md, config):
         super(IncludePreprocessor, self).__init__(md)
         self.base_path = config['base_path']
-    
+        self.encoding = config['encoding']
+
     def run(self, lines):
         done = False
-        
         while not done:
             for line in lines:
                 loc = lines.index(line)
                 m = INC_SYNTAX.search(line)
-                
+
                 if m:
                     filename = m.group(1)
                     filename = os.path.expanduser(filename)
                     if not os.path.isabs(filename):
-                        filename = os.path.normpath(os.path.join(self.base_path,filename))
+                        filename = os.path.normpath(
+                            os.path.join(self.base_path,filename)
+                        )
                     try:
-                        with open(filename, 'r') as r:
+                        with open(filename, 'r', encoding=self.encoding) as r:
                             text = r.readlines()
-                    except:
-                        print('Warning: could not find file {}. Ignoring include statement.'.format(filename))
+                    except Exception, e:
+                        print('Warning: could not find file {}. Ignoring '
+                            'include statement. Error: {}'.format(filename, e))
                         lines[loc] = INC_SYNTAX.sub('',line)
-                        
                         break
-                    
+
                     line_split = INC_SYNTAX.split(line,maxsplit=0)
                     if len(text) == 0: text.append('')
                     for i in range(len(text)):
                         text[i] = text[i][0:-1]
-                    text[0]  = line_split[0] + text[0]
+                    text[0] = line_split[0] + text[0]
                     text[-1] = text[-1] + line_split[2]
                     lines = lines[:loc] + text + lines[loc+1:]
                     break
-            
             else:
                 done = True
-
         return lines
 
 
-
 def makeExtension(*args,**kwargs):
     return MarkdownInclude(kwargs)