chore(plugin-code-blocks): normalize paths, update documentation (#299)

* test(plugin-code-blocks): modify test case * chore(plugin-code-blocks): normalize return values, rework errors * docs(plugin-code-blocks): update documentation
KnodesCommunity · Apr 3, 2023 · e405dc5 · e405dc5
1 parent b2dc4ff
commit e405dc5
Show file tree

Hide file tree

Showing 10 changed files with 40 additions and 29 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,8 +1,8 @@
 {
-    "jest.jestCommandLine": "node_modules\\.bin\\jest",
+    "jest.jestCommandLine": "node_modules/.bin/jest",
     "jest.autoRun": {
         "watch": false,
         "onSave": "test-file"
     },
-    "typescript.tsdk": "node_modules\\typescript\\lib",
+    "typescript.tsdk": "node_modules/typescript/lib",
 }
diff --git a/packages/plugin-code-blocks/__tests__/integration/__snapshots__/simple.spec.ts.snap b/packages/plugin-code-blocks/__tests__/integration/__snapshots__/simple.spec.ts.snap
@@ -48,31 +48,34 @@ exports[`\`index.html\` should have constant content 1`] = `
 				<p>Hello world</p>
 				<details class=\\"code-block\\" open>
 					<summary>
-						<p>From Test inline codeblock from relative</p>
+						<p>From CodeBlock1.json</p>
 					</summary>
 					<pre><code class=\\"language-json\\"><span class=\\"hl-0\\">{</span><span class=\\"hl-1\\">&quot;Foo&quot;</span><span class=\\"hl-0\\">: </span><span class=\\"hl-2\\">&quot;Bar&quot;</span><span class=\\"hl-0\\">}</span>
 </code></pre>
 				</details>
 
+
 				<details class=\\"code-block\\" open>
 					<summary>
-						<p>From Test inline codeblock from project root</p>
+						<p>From CodeBlock2.json</p>
 					</summary>
 					<pre><code class=\\"language-json\\"><span class=\\"hl-0\\">{</span><span class=\\"hl-1\\">&quot;Hello&quot;</span><span class=\\"hl-0\\">: </span><span class=\\"hl-2\\">&quot;World&quot;</span><span class=\\"hl-0\\">}</span>
 </code></pre>
 				</details>
 
+
 				<details class=\\"code-block\\" open>
 					<summary>
-						<p>From Test inline codeblock from module root</p>
+						<p>From CodeBlock3.json</p>
 					</summary>
 					<pre><code class=\\"language-json\\"><span class=\\"hl-0\\">{</span><span class=\\"hl-1\\">&quot;Hello&quot;</span><span class=\\"hl-0\\">: </span><span class=\\"hl-2\\">&quot;World&quot;</span><span class=\\"hl-0\\">}</span>
 </code></pre>
 				</details>
 
+
 				<details class=\\"code-block\\" open>
 					<summary>
-						<p>From example-inline.json</p>
+						<p>From InlineCodeBlock4.json</p>
 					</summary>
 					<pre><code class=\\"language-json\\"><span class=\\"hl-0\\">{</span><span class=\\"hl-1\\">&quot;hello&quot;</span><span class=\\"hl-0\\">: </span><span class=\\"hl-2\\">&quot;world&quot;</span><span class=\\"hl-0\\">}</span>
 </code></pre>
@@ -1646,7 +1649,7 @@ exports[`Inline Codeblock Block tag \`classes/InlineBlock.TestInlineBlock.html\`
 			</section>
 			<aside class=\\"tsd-sources\\">
 				<ul>
-					<li>Defined in inline-codeblock/block.ts:8</li>
+					<li>Defined in inline-codeblock/block.ts:9</li>
 				</ul>
 			</aside>
 			<section class=\\"tsd-panel-group tsd-index-group\\">

diff --git a/packages/plugin-code-blocks/__tests__/integration/simple.spec.ts b/packages/plugin-code-blocks/__tests__/integration/simple.spec.ts
@@ -18,10 +18,10 @@ describe( '`index.html`', describeDocsFile( rootDir, 'index.html', withContent =
 		const panel = dom.window.document.querySelector( '.col-content > .tsd-panel.tsd-typography' );
 		expect( panel!.children ).toHaveLength( 5 );
 		expect( panel!.children[0].outerHTML ).toEqual( '<p>Hello world</p>' );
-		expect( panel!.children[1].outerHTML ).toEqual( formatExpanded( 'Test inline codeblock from relative', SRC_CODE ) );
-		expect( panel!.children[2].outerHTML ).toEqual( formatExpanded( 'Test inline codeblock from project root', EXAMPLE_CODE ) );
-		expect( panel!.children[3].outerHTML ).toEqual( formatExpanded( 'Test inline codeblock from module root', EXAMPLE_CODE ) );
-		expect( panel!.children[4].outerHTML ).toEqual( formatExpanded( 'example-inline.json', INLINE_CODE ) );
+		expect( panel!.children[1].outerHTML ).toEqual( formatExpanded( 'CodeBlock1.json', SRC_CODE ) );
+		expect( panel!.children[2].outerHTML ).toEqual( formatExpanded( 'CodeBlock2.json', EXAMPLE_CODE ) );
+		expect( panel!.children[3].outerHTML ).toEqual( formatExpanded( 'CodeBlock3.json', EXAMPLE_CODE ) );
+		expect( panel!.children[4].outerHTML ).toEqual( formatExpanded( 'InlineCodeBlock4.json', INLINE_CODE ) );
 	} ) );
 	it( 'should have constant content', withContent( content => {
 		expect( formatHtml( content ) ).toMatchSnapshot();

diff --git a/packages/plugin-code-blocks/__tests__/mock-fs/simple/README.md b/packages/plugin-code-blocks/__tests__/mock-fs/simple/README.md
@@ -2,14 +2,23 @@
 
 Hello world
 
-{@codeblock ./src/codeblock/src-test.json | Test inline codeblock from relative}
-{@codeblock ~~:example-test.json | Test inline codeblock from project root}
-{@codeblock ~:example-test.json | Test inline codeblock from module root}
-{@inlineCodeblock example-inline.json ```json
+{@codeblock ./src/codeblock/src-test.json | CodeBlock1.json}
+
+{@codeblock ~~:example-test.json | CodeBlock2.json}
+
+{@codeblock ~:example-test.json | CodeBlock3.json}
+
+{@inlineCodeblock InlineCodeBlock4.json ```json
 {"hello": "world"}
 ```}
 
-@codeblock ./examples/test.json | Test block codeblock
-@inlineCodeblock example-inline.json ```json
+@codeblock ./examples/test.json | CodeBlock5.json
+
+@inlineCodeblock InlineCodeBlock6.json
+```json
+{"hello": "world"}
+```
+
+@inlineCodeblock InlineCodeBlock7.json ```json
 {"hello": "world"}
 ```
diff --git a/packages/plugin-code-blocks/__tests__/mock-fs/simple/src/inline-codeblock/block.ts b/packages/plugin-code-blocks/__tests__/mock-fs/simple/src/inline-codeblock/block.ts
@@ -1,7 +1,8 @@
 /**
  * A test inline code block
  *
- * @inlineCodeblock test.json ```json
+ * @inlineCodeblock test.json
+ * ```json
  * {"hello": "world"}
  * ```
  */

diff --git a/packages/plugin-code-blocks/pages/eslint.md b/packages/plugin-code-blocks/pages/eslint.md
@@ -1,4 +1,4 @@
-While we recommend using `@codeblock` & `@inlineCodeblock` as *inline tags* (eg. `{@codeblock ...}` in any markdown content), you can also use it as block tags defined in your *Typedoc* comments.
+While **only** `{@codeblock}` & `{@inlineCodeblock}` _inline tags_ works in _Markdown_ files, you can also use them as _block tags_ (`@codeblock` & `@inlineCodeblock`, without curly braces) in your _Typedoc comments_.
 
 Example:
 {@codeblock simple/src/codeblock/block.ts#relPath}

diff --git a/packages/plugin-code-blocks/src/converter/reflection-comment-formatter.ts b/packages/plugin-code-blocks/src/converter/reflection-comment-formatter.ts
@@ -22,14 +22,14 @@ class ReflectionCommentFormatter implements IPluginComponent<CodeBlockPlugin>{
 	 * @param match - The block match.
 	 */
 	private _onReplaceCodeBlockBlockTag( { comment, block }: ReflectionCommentReplacer.MatchBlock ){
-		assert.equal( block.content.length, 1 );
 		assert.equal( block.content[0].kind, 'text' );
 		comment.blockTags = without( comment.blockTags, block );
 		const [ main, ...other ] = block.content[0].text.split( '\n' ).map( s => s.trim() );
 		comment.summary.push( { kind: 'text', text: '\n\n' }, { kind: 'inline-tag', tag: '@codeblock', text: main } );
 		if( other.length > 0 ){
 			comment.summary.push( { kind:'text', text: [ '', ...other ].join( '\n' ) } );
 		}
+		comment.summary.push( ...block.content.slice( 1 ) );
 	}
 
 	/**

diff --git a/packages/plugin-code-blocks/src/output/markdown-code-blocks.spec.ts b/packages/plugin-code-blocks/src/output/markdown-code-blocks.spec.ts
@@ -1,5 +1,5 @@
 import { noop } from 'lodash';
-import { DeclarationReflection, ReflectionKind, RepositoryType, normalizePath } from 'typedoc';
+import { DeclarationReflection, ReflectionKind, RepositoryType } from 'typedoc';
 
 import { resolve } from '@knodes/typedoc-pluginutils/path';
 
@@ -62,7 +62,7 @@ describe( 'Behavior', () => {
 		expect( markdownReplacerTestbed.runMarkdownReplace( text ) ).toEqual( text );
 	} );
 	describe( 'Code block generation', ()=> {
-		const sourceFile = normalizePath( resolve( rootDir, FILE ) );
+		const sourceFile = resolve( rootDir, FILE );
 		interface IBlockGenerationAssertion{
 			renderCall: Partial<ICodeBlock>;
 			blocks: Array<[string, {code: string;startLine: number;endLine: number}]>;

diff --git a/packages/plugin-code-blocks/src/output/markdown-code-blocks.ts b/packages/plugin-code-blocks/src/output/markdown-code-blocks.ts
@@ -2,7 +2,7 @@ import assert from 'assert';
 
 import { isString, uniq } from 'lodash';
 import { filter as filterGlob } from 'minimatch';
-import { DeclarationReflection, ReflectionKind, RepositoryType, normalizePath } from 'typedoc';
+import { DeclarationReflection, ReflectionKind, RepositoryType } from 'typedoc';
 
 import { CurrentPageMemo, IPluginComponent, MarkdownReplacer, reflectionKindUtils, reflectionSourceUtils, resolveNamedPath } from '@knodes/typedoc-pluginutils';
 import { relative } from '@knodes/typedoc-pluginutils/path';
@@ -46,7 +46,7 @@ export class MarkdownCodeBlocks implements IPluginComponent<CodeBlockPlugin>{
 	private _replaceInlineCodeBlock( match: MarkdownReplacer.Match ) {
 		// Avoid recursion in code blocks
 		if( this._currentPageMemo.currentReflection instanceof DeclarationReflection && this._currentPageMemo.currentReflection.kind === CODEBLOCK_KIND ){
-			return;
+			return undefined;
 		}
 		const [ fileName, blockModeStr, markdownCode ] = match.captures;
 		assert.ok( fileName );
@@ -70,7 +70,7 @@ export class MarkdownCodeBlocks implements IPluginComponent<CodeBlockPlugin>{
 	private _replaceCodeBlock( match: MarkdownReplacer.Match, sourceHint: MarkdownReplacer.SourceHint ) {
 		// Avoid recursion in code blocks
 		if( this._currentPageMemo.currentReflection instanceof DeclarationReflection && this._currentPageMemo.currentReflection.kind === CODEBLOCK_KIND ){
-			return;
+			return undefined;
 		}
 		const [ file, block, blockModeStr, fakedFileName ] = match.captures;
 		try {
@@ -109,9 +109,6 @@ export class MarkdownCodeBlocks implements IPluginComponent<CodeBlockPlugin>{
 			this._currentPageMemo.currentReflection,
 			this.plugin.pluginOptions.getValue().source,
 			file );
-		if( !resolvedFile ){
-			throw new Error( `Could not resolve file ${file}` );
-		}
 		// Get the actual code sample
 		if( !this._fileSamples.has( resolvedFile ) ){
 			this._fileSamples.set( resolvedFile, readCodeSample( resolvedFile ) );
@@ -191,7 +188,7 @@ export class MarkdownCodeBlocks implements IPluginComponent<CodeBlockPlugin>{
 	 * @returns the file name to show in the header.
 	 */
 	private _getHeaderFileName( file: string, lineRange: readonly [number, number] | null ): string {
-		const filePath = normalizePath( relative( this.plugin.rootDir, file ) );
+		const filePath = relative( this.plugin.rootDir, file );
 		const regionMarker = lineRange ? `#${lineRange[0]}~${lineRange[1]}` : '';
 		return `./${filePath}${regionMarker}`;
 	}

diff --git a/typedoc.js b/typedoc.js
@@ -59,6 +59,7 @@ module.exports = {
 	// #endregion
 	pluginCodeBlocks: {
 		source: '__tests__/mock-fs',
+		excludeMarkdownTags: [ '{@codeblock}', '{@inlineCodeblock}' ],
 	},
 	excludePrivate: true,
 	// #region pagesConfig-5