Add plugin to import sections of readme into the documentation

README.md

@@ -5,6 +5,8 @@ cibuildwheel
 
 [Documentation](https://cibuildwheel.readthedocs.org)
 
+<!--intro-start-->
+
 Python wheels are great. Building them across **Mac, Linux, Windows**, on **multiple versions of Python**, is not.
 
 `cibuildwheel` is here to help. `cibuildwheel` runs on your CI server - currently it supports Azure Pipelines, Travis CI, AppVeyor, and CircleCI - and it builds and tests your wheels across all of your platforms.
@@ -34,6 +36,8 @@ Usage
 
 `cibuildwheel` is not intended to run on your development machine. Because it uses system Python from Python.org it will try to install packages globally - not what you expect from a build tool! Instead, isolated CI services like Travis CI, CircleCI, Azure Pipelines and AppVeyor are ideal.
 
+<!--intro-end-->
+
 Example setup
 -------------
 

docs/index.md

@@ -4,3 +4,9 @@ Home
 Welcome to the cibuildwheel docs. 
 
 To get started, head over to the [setup guide](setup.md).
+
+{% 
+   includemarkdown "../README.md"
+   start="<!--intro-start-->" 
+   end="<!--intro-end-->"
+%}

docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/plugin.py

@@ -0,0 +1,53 @@
+import mkdocs, re, os, io, cgi
+from pprint import pprint
+
+TAG_REGEX_PATTERN = re.compile(
+    r'''
+        {% # opening tag
+        \s*
+        includemarkdown # directive name
+        \s+
+        "(?P<filename>[^"]+)" # "filename"
+        (?:\s+start="(?P<start>[^"]+)")? # optional start expression
+        (?:\s+end="(?P<end>[^"]+)")? # optional end expression
+        \s*
+        %} # closing tag
+    ''',
+    flags=re.VERBOSE,
+)
+
+class ImportMarkdownPlugin(mkdocs.plugins.BasePlugin):
+    def on_page_markdown(self, markdown, page, **kwargs):
+        page_src_path = page.file.abs_src_path
+
+        def found_import_markdown_tag(match):
+            filename = match.group('filename')
+            start = match.group('start')
+            end = match.group('end')
+            print('got a match', filename, start, end)
+
+            file_path_abs = os.path.join(os.path.dirname(page_src_path), filename)
+
+            if not os.path.exists(file_path_abs):
+                raise ValueError('file not found', filename)
+
+            with io.open(file_path_abs, encoding='utf8') as f:
+                text_to_include = f.read()
+            
+            if start:
+                _, _, text_to_include = text_to_include.partition(start)
+
+            if end:
+                text_to_include, _, _ = text_to_include.partition(end)
+            
+            return (
+                '<!-- BEGIN INCLUDE %s %s %s -->' % (
+                    filename, cgi.escape(start), cgi.escape(end)
+                )
+                + text_to_include
+                + '<!-- END INCLUDE -->'
+            )
+
+        markdown = re.sub(TAG_REGEX_PATTERN, found_import_markdown_tag, markdown)
+        return markdown
+    

docs/mkdocs_include_markdown_plugin/setup.py

@@ -0,0 +1,15 @@
+from setuptools import setup
+
+setup(
+    name='mkdocs_include_markdown_plugin',
+    version='1.0',
+    author='Joe Rickerby',
+    license='Apache 2',
+    packages=['mkdocs_include_markdown_plugin'],
+    entry_points={
+        'mkdocs.plugins': [
+            'importmarkdown = mkdocs_include_markdown_plugin.plugin:ImportMarkdownPlugin',
+        ]
+    },
+    zip_safe=False
+)

mkdocs.yml

@@ -27,3 +27,6 @@ markdown_extensions:
       permalink: True
   - attr_list
   - admonition
+
+plugins:
+  - importmarkdown