A VSCode extension providing a set of simple utilities to aid in authoring/viewing Angular documentation source code.
The extension is only intended for people working with the source code of the Angular documentation content (e.g. authors, core contributors).
The extension provides features that are useful for viewing and authoring code snippets (with source code extracted from standalone apps) in Angular API docs and guides.
Hovering over <code-example>, <code-pane> or {@example} tags shows the extracted code snippets, including their header and line numbering.
Note: Both header and title attributes are recognized for backwards compatibility.
Right-clicking on <code-example>, <code-pane> or {@example} tags shows context menu options for peeking the definition (source code regions) and navigating to the definition (source code file) of the code snippet.
If the code snippet consists of multiple docregions, all regions are highlighted.
When creating <code-example>, <code-pane> or {@example} tags, autocomplete suggestions are shown for the region attribute.
Note: Autocomplete suggestions are triggered by the characters = (after region) and '/" (after region=).
GIFs captured with ScreenToGif ❀
The extension enhances the generated previews of documentation Markdown files (mainly guides in the aio/content/ directory and its sub-directories).
Due to how the angular.io build system works, the local images referenced in guides will be served from a generated/images/ directory in production. During development, images are (usually) located in the aio/src/generated/images/ directory. The extension fixes the URLs of such images in Markdown previews, so that they point to the correct image files on disk and thus correctly show up in the preview.
Before the fix:
After the fix:
See here for a list of releases.
See here a list of changes.
You can find the latest published version here.
The examples in the actual docs are processed via dgeni and more specifically using utilities in the examples-package.
This extension re-implements the relevant logic, but might have slight inconsistencies compared to the actual dgeni implementation.
{@example ...} tags spreading across multi lines will not be recognized if there are lines that contain only unnamed attributes (such as the path or header). For example:
These will not be recognized:
{@example
path/to/examp.le
region="foo"
}
{@example path/to/examp.le region="foo"
This is the header
}
These will be recognized:
{@example
path/to/examp.le region="foo"
}
{@example path/to/examp.le region="foo"
header="This is the header"
}
{@example path/to/examp.le
region="foo" This is the header
}
7E41
Things I want to (but won't necessarily) do:
- Investigate/Add ability to preview app in
WebView > iframe. E.g.:(References: https://code.visualstudio.com/api/extension-guides/webview)const panel = window.createWebviewPanel('foo', 'Hello, world!', ViewColumn.Active, { enableScripts: true, retainContextWhenHidden: true, }); panel.webview.html = ` <!DOCTYPE html> <html> <head> <style> html, body { margin: 0; overflow: hidden; padding: 0; } iframe { border: none; height: 100vh; width: 100vw; } </style> </head> <body> <iframe src="http://localhost:4200/"></iframe> </body> </html> `;
- Add e2e tests.
- Add tests for
src/test/helpers/e2e-runner.ts. - Consider using
webpackfor start-up time (and overall perf?) improvement. (References: https://medium.com/@fabiospampinato/why-i-wrote-33-vscode-extensions-and-how-i-manage-them-cb61df05e154, https://code.visualstudio.com/updates/v1_29#_bundling-extensions) - Investigate switching from AppVeyor to Travis for testing on Windows (once https://travis-ci.community/t/windows-instances-hanging-before-install/250 has been resolved).
- Refactor
CodeSnippetUtilsinto separate (independently unit-testable) "parsers" for different types of tags (HtmlTag,NgdocTag, etc.), that would returnICodeSnippetRawInfoandICodeSnippetAttrInfo.