Merge pull request #231 from YannickJadoul/docs-include-examples

Including CI configurations from examples into docs

docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/plugin.py

@@ -1,6 +1,19 @@
 import mkdocs, re, os, io, cgi
 
-TAG_REGEX_PATTERN = re.compile(
+INCLUDE_TAG_REGEX = re.compile(
+    r'''
+        {% # opening tag
+        \s*
+        include # directive name
+        \s+
+        "(?P<filename>[^"]+)" # "filename"
+        \s*
+        %} # closing tag
+    ''',
+    flags=re.VERBOSE,
+)
+
+INCLUDEMARKDOWN_TAG_REGEX = re.compile(
     r'''
         {% # opening tag
         \s*
@@ -19,7 +32,25 @@ 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):
+        def found_include_tag(match):
+            filename = match.group('filename')
+
+            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()
+
+            # Allow good practice of having a final newline in the file
+            if text_to_include.endswith('\n'):
+                text_to_include = text_to_include[:-1]
+
+            return text_to_include
+
+
+        def found_includemarkdown_tag(match):
             filename = match.group('filename')
             start = match.group('start')
             end = match.group('end')
@@ -39,13 +70,14 @@ class ImportMarkdownPlugin(mkdocs.plugins.BasePlugin):
                 text_to_include, _, _ = text_to_include.partition(end)
             
             return (
-                '<!-- BEGIN INCLUDE %s %s %s -->' % (
+                '<!-- BEGIN INCLUDE %s %s %s -->\n' % (
-                    filename, cgi.escape(start), cgi.escape(end)
+                    filename, cgi.escape(start or ''), cgi.escape(end or '')
                 )
                 + text_to_include
-                + '<!-- END INCLUDE -->'
+                + '\n<!-- END INCLUDE -->'
             )
 
-        markdown = re.sub(TAG_REGEX_PATTERN, found_import_markdown_tag, markdown)
+        markdown = re.sub(INCLUDE_TAG_REGEX, found_include_tag, markdown)
+        markdown = re.sub(INCLUDEMARKDOWN_TAG_REGEX, found_includemarkdown_tag, markdown)
         return markdown
     

docs/setup.md

@@ -8,39 +8,7 @@ Using Azure pipelines, you can build all three platforms on the same service. Cr
 
 > azure-pipelines.yml
 ```yaml
-jobs:
+{% include "../examples/azure-pipelines-minimal.yml" %}
-- job: linux
-  pool: {vmImage: 'Ubuntu-16.04'}
-  steps:
-    - task: UsePythonVersion@0
-    - bash: |
-        python -m pip install --upgrade pip
-        pip install cibuildwheel==1.1.0
-        cibuildwheel --output-dir wheelhouse .
-    - task: PublishBuildArtifacts@1
-      inputs: {pathtoPublish: 'wheelhouse'}
-- job: macos
-  pool: {vmImage: 'macOS-10.13'}
-  steps:
-    - task: UsePythonVersion@0
-    - bash: |
-        python -m pip install --upgrade pip
-        pip install cibuildwheel==1.1.0
-        cibuildwheel --output-dir wheelhouse .
-    - task: PublishBuildArtifacts@1
-      inputs: {pathtoPublish: 'wheelhouse'}
-- job: windows
-  pool: {vmImage: 'vs2017-win2016'}
-  steps:
-    - task: UsePythonVersion@0
-    - script: choco install vcpython27 -f -y
-      displayName: Install Visual C++ for Python 2.7
-    - bash: |
-        python -m pip install --upgrade pip
-        pip install cibuildwheel==1.1.0
-        cibuildwheel --output-dir wheelhouse .
-    - task: PublishBuildArtifacts@1
-      inputs: {pathtoPublish: 'wheelhouse'}
 ```
 
 Commit this file, enable building of your repo on Azure Pipelines, and push.
@@ -53,33 +21,7 @@ To build Linux, Mac, and Windows wheels on Travis CI, create a `.travis.yml` fil
 
 > .travis.yml
 ```yaml
-language: python
+{% include "../examples/travis-ci-minimal.yml" %}
-
-jobs:
-  include:
-    # perform a linux build
-    - services: docker
-    # and a mac build
-    - os: osx
-      language: shell
-    # and a windows build
-    - os: windows
-      language: shell
-      before_install:
-        - choco install python --version 3.8.0
-        - export PATH="/c/Python38:/c/Python38/Scripts:$PATH"
-
-env:
-  global:
-    - TWINE_USERNAME=joerick
-      # Note: TWINE_PASSWORD is set in Travis settings
-
-install:
-  - python -m pip install twine cibuildwheel==1.1.0
-
-script:
-  # build the wheels, put them into './wheelhouse'
-  - python -m cibuildwheel --output-dir wheelhouse
 ```
 
 Note that building Windows Python 2.7 wheels on Travis is unsupported.
@@ -94,44 +36,7 @@ To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file
 
 > .circleci/config.yml
 ```yaml
-version: 2
+{% include "../examples/circleci-minimal.yml" %}
-
-jobs:
-  linux-wheels:
-    working_directory: ~/linux-wheels
-    docker:
-      - image: circleci/python:3.6
-    steps:
-      - checkout
-      - setup_remote_docker
-      - run:
-          name: Build the Linux wheels.
-          command: |
-            pip install --user cibuildwheel==1.1.0
-            cibuildwheel --output-dir wheelhouse
-      - store_artifacts:
-          path: wheelhouse/
-
-  osx-wheels:
-    working_directory: ~/osx-wheels
-    macos:
-      xcode: "10.0.0"
-    steps:
-      - checkout
-      - run:
-          name: Build the OS X wheels.
-          command: |
-            pip install --user cibuildwheel==1.1.0
-            cibuildwheel --output-dir wheelhouse
-      - store_artifacts:
-          path: wheelhouse/
-
-workflows:
-  version: 2
-  all-tests:
-    jobs:
-      - linux-wheels
-      - osx-wheels
 ```
 
 Commit this file, enable building of your repo on CircleCI, and push.
@@ -148,19 +53,7 @@ To build Linux and Windows wheels on AppVeyor, create an `appveyor.yml` file in
 > appveyor.yml
 
 ```yaml
-image:
+{% include "../examples/appveyor-minimal.yml" %}
-  - Ubuntu
-  - Visual Studio 2015
-build_script:
-  # windows
-  - cmd: pip install cibuildwheel==1.1.0
-  - cmd: cibuildwheel --output-dir wheelhouse
-  # linux
-  - sh: "${HOME}/.localpython3.7.4/bin/python3 -m pip install cibuildwheel==1.1.0"
-  - sh: "${HOME}/.localpython3.7.4/bin/python3 -m cibuildwheel --output-dir wheelhouse"
-artifacts:
-  - path: "wheelhouse\\*.whl"
-    name: Wheels
 ```
 
 Commit this file, enable building of your repo on AppVeyor, and push.

examples/appveyor-minimal.yml

@@ -0,0 +1,15 @@
+image:
+  - Ubuntu
+  - Visual Studio 2015
+
+build_script:
+  # windows
+  - cmd: pip install cibuildwheel==1.1.0
+  - cmd: cibuildwheel --output-dir wheelhouse
+  # linux
+  - sh: "${HOME}/.localpython3.7.4/bin/python3 -m pip install cibuildwheel==1.1.0"
+  - sh: "${HOME}/.localpython3.7.4/bin/python3 -m cibuildwheel --output-dir wheelhouse"
+
+artifacts:
+  - path: "wheelhouse\\*.whl"
+    name: Wheels

examples/azure-pipelines-minimal.yml

@@ -0,0 +1,35 @@
+jobs:
+- job: linux
+  pool: {vmImage: 'Ubuntu-16.04'}
+  steps:
+    - task: UsePythonVersion@0
+    - bash: |
+        python -m pip install --upgrade pip
+        pip install cibuildwheel==1.1.0
+        cibuildwheel --output-dir wheelhouse .
+    - task: PublishBuildArtifacts@1
+      inputs: {pathtoPublish: 'wheelhouse'}
+
+- job: macos
+  pool: {vmImage: 'macOS-10.13'}
+  steps:
+    - task: UsePythonVersion@0
+    - bash: |
+        python -m pip install --upgrade pip
+        pip install cibuildwheel==1.1.0
+        cibuildwheel --output-dir wheelhouse .
+    - task: PublishBuildArtifacts@1
+      inputs: {pathtoPublish: 'wheelhouse'}
+
+- job: windows
+  pool: {vmImage: 'vs2017-win2016'}
+  steps:
+    - task: UsePythonVersion@0
+    - script: choco install vcpython27 -f -y
+      displayName: Install Visual C++ for Python 2.7
+    - bash: |
+        python -m pip install --upgrade pip
+        pip install cibuildwheel==1.1.0
+        cibuildwheel --output-dir wheelhouse .
+    - task: PublishBuildArtifacts@1
+      inputs: {pathtoPublish: 'wheelhouse'}

examples/circleci-minimal.yml

@@ -0,0 +1,38 @@
+version: 2
+
+jobs:
+  linux-wheels:
+    working_directory: ~/linux-wheels
+    docker:
+      - image: circleci/python:3.6
+    steps:
+      - checkout
+      - setup_remote_docker
+      - run:
+          name: Build the Linux wheels.
+          command: |
+            pip install --user cibuildwheel==1.1.0
+            cibuildwheel --output-dir wheelhouse
+      - store_artifacts:
+          path: wheelhouse/
+
+  osx-wheels:
+    working_directory: ~/osx-wheels
+    macos:
+      xcode: "10.0.0"
+    steps:
+      - checkout
+      - run:
+          name: Build the OS X wheels.
+          command: |
+            pip install --user cibuildwheel==1.1.0
+            cibuildwheel --output-dir wheelhouse
+      - store_artifacts:
+          path: wheelhouse/
+
+workflows:
+  version: 2
+  all-tests:
+    jobs:
+      - linux-wheels
+      - osx-wheels

examples/travis-ci-minimal.yml

@@ -0,0 +1,22 @@
+language: python
+
+jobs:
+  include:
+    # perform a linux build
+    - services: docker
+    # and a mac build
+    - os: osx
+      language: shell
+    # and a windows build
+    - os: windows
+      language: shell
+      before_install:
+        - choco install python --version 3.8.0
+        - export PATH="/c/Python38:/c/Python38/Scripts:$PATH"
+
+install:
+  - python -m pip install cibuildwheel==1.1.0
+
+script:
+  # build the wheels, put them into './wheelhouse'
+  - python -m cibuildwheel --output-dir wheelhouse

examples/travis-ci-test-and-deploy.yml

@@ -74,4 +74,3 @@ env:
   global:
     - TWINE_USERNAME=joerick
       # Note: TWINE_PASSWORD is set in Travis settings
-