Angular.io Documentation Utilities

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).

   

Features

NOTE:
This extension offers experimental support for VSCode for the web (i.e. the in-browser version of VSCode, as seen on github.dev for example).
_{If you find that a feature is not working properly on the web, please file an issue.}

Code snippet utilities

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.

Show code snippets on hover

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.

Peek/Go to code snippet definition

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.

Autocomplete suggestions for docregions

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 ❀}

Markdown preview enhancement

The extension enhances the generated previews of documentation Markdown files (mainly guides in the aio/content/ directory and its sub-directories).

Fix URLs to local images

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 located in the aio/content/images/ directory (from where they are copied to aio/src/generated/images/ and from there to aio/dist/generated/).

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:

Fix code snippets display

Code snippets are included in guides as <code-example> elements or <code-tabs> with one or more <code-pane> elements (for tabbed code snippets). In guide previews, these unknown HTML elements are not shown at all, making the preview a bit misleading.

The extension transforms these elements in Markdown previews, so that they are shown as code blocks (with appropriate formatting to improve readability).

Before the fix:

After the fix:

Releases

See here for a list of releases.
See here a list of changes.

You can find the latest published version here.

Known issues

Possible inconsistency with the actual implementation

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.

Multi-line {@example ...} tags not fully supported

{@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
}

---

TODO

Things I want to (but won't necessarily) do:

• Add e2e tests.
• Run e2e (and unit?) tests in a browser environment. Instructions: https://code.visualstudio.com/api/extension-guides/web-extensions#test-your-web-extension
  (NOTE: The in-browser tests might be affected by Issue 133399.)
• Consider adding a shortcut for opening http://localhost:4200/ inside the editor to preview the app (using the built-in simpleBrowser.show command).
• Investigate possible fixGuideCodeSnippetsPlugin() improvements:
  • Improvement 1: Parse and show snippet info (header, path, region, etc.).
    • Investigate parsing snippets (without file info).
      • Make CodeSnippetUtils#getInfo() (getInfoHtml()?) more easily reusable.
    • Replace current <pre></pre> code block with a more structured representation of the parsed info.
  • Improvement 2: Show snippet content (requires containing document?).
    • Investigate getting doc from active editor or open editor (matched by code snippet opening tag) and parsing snippets fully (with content). E.g.:
      • Modify CodeSnippetUtils to be able to extract info directly from content (instead of TextDocument + Position).
      • Use window.activeTextEditor.document.uri to resolve the example path. Ideally, this would need to be matched against the correct provider so that the example path could be resolved correctly (and also skip work for non-matching Markdown files). For extra confirmation, I could use the opening tag string and search for it in the active document. (Do I need to deal with formatting (e.g. whitespace)?)
      • Extract the code snippet attributes and content and show them in the Markdown preview. This is very similar to CodeSnippetIntellisenseProvider#provideHover(). Investigate reuse opportunities.
• Refactor CodeSnippetUtils into separate (independently unit-testable) "parsers" for different types of tags (HtmlTag, NgdocTag, etc.), that would return ICodeSnippetRawInfo and ICodeSnippetAttrInfo.