Angular.io Documentation Utilities

AVSCodeextension providing a set of simple utilities to aid in authoring/viewingAngular documentationsource code.

The extension is only intended for people working with the source code of theAngular documentationcontent (e.g. authors, core contributors).

   

Features

NOTE:
This extension offers experimental support forVSCode for the web(i.e. the in-browser version of VSCode, as seen ongithub.devfor example).
_{If you find that a feature is not working properly on the web, pleasefile 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) inAngularAPI 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:Bothheaderandtitleattributes 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 theregionattribute.

Note:Autocomplete suggestions are triggered by the characters=(afterregion) and'/"(afterregion=).

_{GIFs captured withScreenToGif❀}

Markdown preview enhancement

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

Fix URLs to local images

Due to how theangular.iobuild system works, the local images referenced in guides will be served from agenerated/images/directory in production. During development, images are located in theaio/content/images/directory (from where they are copied toaio/src/generated/images/and from there toaio/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

Seeherefor a list of releases.
Seeherea list of changes.

You can find the latest published versionhere.

Known issues

Possible inconsistency with the actual implementation

The examples in the actual docs are processed viadgeniand more specifically using utilities in theexamples-package.
This extension re-implements the relevant logic, but might have slight inconsistencies compared to the actualdgeniimplementation.

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:

Thesewill notbe recognized:

{@example
path/to/examp.le
region= "foo"
}

{@example path/to/examp.le region= "foo"
This is the header
}

Thesewillbe 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 /api/extension-guides/web-extensions#test-your-web-extension
  (NOTE: The in-browser tests might be affected byIssue 133399.)
• Consider adding a shortcut for openinghttp://localhost:4200/inside the editor to preview the app (using the built-insimpleBrowser.showcommand).
• Investigate possiblefixGuideCodeSnippetsPlugin()improvements:
  • Improvement 1: Parse and show snippet info (header, path, region, etc.).
    • Investigate parsing snippets (without file info).
      • MakeCodeSnippetUtils#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.:
      • ModifyCodeSnippetUtilsto be able to extract info directly from content (instead ofTextDocument+Position).
      • Usewindow.activeTextEditor.document.urito 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 toCodeSnippetIntellisenseProvider#provideHover().Investigate reuse opportunities.
• RefactorCodeSnippetUtilsinto separate (independently unit-testable) "parsers" for different types of tags (HtmlTag,NgdocTag,etc.), that would returnICodeSnippetRawInfoandICodeSnippetAttrInfo.