Merge pull request #1 from cloudnc/refactor/compilable-markdown-codeb…

…locks

docs(Readme): Add tooling to make readme embedded code written in typ…

.travis.yml

@@ -27,8 +27,8 @@ script:
 #  - yarn run demo:test:e2e:ci
   - sed -i 's/<base href="\/">/<base href="https:\/\/cloudnc.github.io\/observable-webworker\/">/g' dist/observable-webworker-demo/index.html
 
-  - rm dist/observable-webworker/README.md && cp README.md dist/observable-webworker
   - cp LICENSE dist/observable-webworker
+  - yarn readme:build
 
 deploy:
   - provider: script

README.md

@@ -21,39 +21,11 @@ yarn add observable-webworker
 
 ### Quickstart
 
-```ts
-// hello.worker.ts
+```src/readme/hello.ts
 
-import { ObservableWorker, DoWork, GenericWorkerMessage } from 'observable-webworker';
-import { Observable } from 'rxjs';
-import { map } from 'rxjs/operators';
-
-@ObservableWorker()
-class HelloWorker implements DoWork<string, string> {
-  public work(input$: Observable<GenericWorkerMessage<string>>): Observable<GenericWorkerMessage<string>> {
-    return input$.pipe(
-      map(message => {
-        console.log(message); // outputs 'Hello from main thread'
-        return {
-          payload: `Hello from webworker`,
-        };
-      }),
-    );
-  }
-}
 ```
 
-```ts
-// hello.ts
-import { fromWorker } from 'observable-webworker';
-import { of } from 'rxjs';
-import { map } from 'rxjs/operators';
-
-fromWorker<string, string>(() => new Worker('./hello.worker', { type: 'module' }, of('Hello from main thread')).pipe(
-  map(res => res.payload),
-).subscribe(message => {
-  console.log(message); // Outputs 'Hello from webworker'
-})
+```src/readme/hello.worker.ts
 
 ```
 
@@ -62,25 +34,6 @@ fromWorker<string, string>(() => new Worker('./hello.worker', { type: 'module' }
 If decorators is not something you use regularly and prefer direct functions, simply
 use the `runWorker` function instead.
 
-```ts
-// hello.worker.ts
-
-import { runWorker, DoWork, GenericWorkerMessage } from 'observable-webworker';
-import { Observable } from 'rxjs';
-import { map } from 'rxjs/operators';
-
-class HelloWorker implements DoWork<string, string> {
-  public work(input$: Observable<GenericWorkerMessage<string>>): Observable<GenericWorkerMessage<string>> {
-    return input$.pipe(
-      map(message => {
-        console.log(message); // outputs 'Hello from main thread'
-        return {
-          payload: `Hello from webworker`,
-        };
-      }),
-    );
-  }
-}
+```src/readme/hello-no-decorator.worker.ts#L4-L20
 
-runWorker(HelloWorker);
 ```

markdown-code-embed.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { extname } from 'path';
+
+/**
+ * This simple script looks for code fences in source file for a syntax that looks like a file reference, optionally with a line number
+ * reference. If a file exists at this location it is inserted into the code fence.
+ *
+ * Example:
+ *
+ * ```path/to/some/file.ts
+ * ```
+ *
+ * will look for path/to/some/file.ts and if present, read it and insert
+ *
+ * ```ts
+ * // file content will appear hear
+ * ```
+ *
+ * ```path/to/some/file.ts#L10-50
+ * ```
+ *
+ * ```ts
+ * // file content (only lines 10 - 50) will appear hear
+ * ```
+ *
+ *
+ */
+
+const [proc, thisFile, source, outputFile] = process.argv;
+
+const sourceText = readFileSync(source, 'utf-8');
+
+const output = sourceText.replace(/```([\S]*)$\n([\s\S]*?)\n?```/gm, (substr: string, codeExtension: string) => {
+  const matches = codeExtension.match(/\s?(\S+?)((#L(\d+)-L(\d+))|$)/m);
+
+  if (!matches) {
+    return substr;
+  }
+
+  const [_, filename, __, lineNumbering, startLine, endLine] = matches;
+
+  if (!existsSync(filename)) {
+    return substr;
+  }
+
+  const extension = extname(filename).slice(1);
+  const file = readFileSync(filename, 'utf8');
+
+  let outputCode = file;
+
+  if (lineNumbering) {
+    const lines = file.split('\n');
+
+    outputCode = lines.slice(+startLine - 1, +endLine).join('\n');
+  }
+
+  return `
+\`\`\`${extension}
+${outputCode}
+\`\`\`
+  `;
+});
+
+console.log(output);
+writeFileSync(outputFile, output);

package.json

@@ -26,6 +26,7 @@
     "lib:test:ci": "yarn run ng test --project observable-webworker --watch false",
     "------------------ RELEASE COMMANDS ------------------": "",
     "semantic-release": "semantic-release",
+    "readme:build": "ts-node --skip-project markdown-code-embed.ts README.md dist/observable-webworker/README.md",
     "------------------ QUICK COMMANDS ------------------": "",
     "lint:fix": "yarn demo:lint:fix && yarn prettier:write",
     "test": "yarn lib:test:watch",

src/readme/hello-no-decorator.worker.ts

@@ -0,0 +1,19 @@
+// hello-no-decorator.worker.ts
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { runWorker, DoWork, GenericWorkerMessage } from 'observable-webworker';
+
+class HelloWorker implements DoWork<string, string> {
+  public work(input$: Observable<GenericWorkerMessage<string>>): Observable<GenericWorkerMessage<string>> {
+    return input$.pipe(
+      map(message => {
+        console.log(message); // outputs 'Hello from main thread'
+        return {
+          payload: `Hello from webworker`,
+        };
+      }),
+    );
+  }
+}
+
+runWorker(HelloWorker);

src/readme/hello.ts

@@ -0,0 +1,12 @@
+// hello.ts
+import { fromWorker } from 'observable-webworker';
+import { of } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+const input$ = of({ payload: 'Hello from main thread' });
+
+fromWorker<string, string>(() => new Worker('./hello.worker', { type: 'module' }), input$)
+  .pipe(map(res => res.payload))
+  .subscribe(message => {
+    console.log(message); // Outputs 'Hello from webworker'
+  });

src/readme/hello.worker.ts

@@ -0,0 +1,19 @@
+// hello.worker.ts
+
+import { ObservableWorker, DoWork, GenericWorkerMessage } from 'observable-webworker';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+@ObservableWorker()
+class HelloWorker implements DoWork<string, string> {
+  public work(input$: Observable<GenericWorkerMessage<string>>): Observable<GenericWorkerMessage<string>> {
+    return input$.pipe(
+      map(message => {
+        console.log(message); // outputs 'Hello from main thread'
+        return {
+          payload: `Hello from webworker`,
+        };
+      }),
+    );
+  }
+}