Add docs on how to include other files - fix #1902 (#2638)

Add docs on how to include other files - fix #1902

docs/content.rst

@@ -389,6 +389,40 @@ to allow linking to both generated articles and pages and their static sources.
 
 Support for the old syntax may eventually be removed.
 
+Including other files
+---------------------
+Both Markdown and reStructuredText syntaxes provide mechanisms for this.
+
+Following below are some examples for **reStructuredText** using `the include directive`_:
+
+    .. code-block:: rst
+
+        .. include:: file.rst
+
+Include a fragment of a file delimited by two identifiers, highlighted as C++ (slicing based on line numbers is also possible):
+
+    .. code-block:: rst
+
+        .. include:: main.cpp
+            :code: c++
+            :start-after: // begin
+            :end-before: // end
+
+Include a raw HTML file (or an inline SVG) and put it directly into the output without any processing:
+
+    .. code-block:: rst
+
+        .. raw:: html
+            :file: table.html
+
+For **Markdown**, one must rely on an extension. For example, using the `mdx_include plugin`_:
+
+    .. code-block:: none
+
+        ```html
+        {! template.html !}
+        ```
+
 
 Importing an existing site
 ==========================
@@ -582,3 +616,5 @@ metadata to include ``Status: published``.
 .. _Markdown Extensions: https://python-markdown.github.io/extensions/
 .. _CodeHilite extension: https://python-markdown.github.io/extensions/code_hilite/#syntax
 .. _i18n_subsites plugin: https://github.com/getpelican/pelican-plugins/tree/master/i18n_subsites
+.. _the include directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#include
+.. _mdx_include plugin: https://github.com/neurobin/mdx_include

pelican/generators.py

@@ -155,16 +155,15 @@ class Generator(object):
 
             if os.path.isdir(root):
                 for dirpath, dirs, temp_files in os.walk(
-                        root, followlinks=True):
+                        root, topdown=True, followlinks=True):
-                    drop = []
                     excl = exclusions_by_dirpath.get(dirpath, ())
-                    for d in dirs:
+                    # We copy the `dirs` list as we will modify it in the loop:
+                    for d in list(dirs):
                         if (d in excl or
                             any(fnmatch.fnmatch(d, ignore)
                                 for ignore in ignores)):
-                            drop.append(d)
+                            if d in dirs:
-                    for d in drop:
+                                dirs.remove(d)
-                        dirs.remove(d)
 
                     reldir = os.path.relpath(dirpath, self.path)
                     for f in temp_files:

pelican/tests/support.py

@@ -188,7 +188,7 @@ class LogCountHandler(BufferingHandler):
     """Capturing and counting logged messages."""
 
     def __init__(self, capacity=1000):
-        logging.handlers.BufferingHandler.__init__(self, capacity)
+        super(LogCountHandler, self).__init__(capacity)
 
     def count_logs(self, msg=None, level=None):
         return len([