docs-cog-services v0.0.1-e

Smart docs

Documentation infused with smarts.

• keyphrase extraction for displayName metadata tag, provided by Azure Cognitive Services' Text Analytics

Whose smarts?

Smarts are provided in the following ways:

• parsing markdown into JSON
• providing Cognitive/AI values for relevant parts of docs such as keyphrases
• ignoring parts of doc that don't provide immediate user value (codeblocks)
• ignoring parts that are already overly emphasized in text, such as branding (an example Azure)

How are the smarts provided

TocManager's constructor includes the values to call Text Analytics Keyword detection

How to use this library

This library can be used as the middleware between an IDE such as VS Code (via extensions) and a markdown doc.

Required Azure Cognitive Services

1. Create an Azure resource for Text analytics.

2. Copy .env.sample, name the file .env, and set your own values:

   TA_KEY=
   TA_HOST=westus.api.cognitive.microsoft.com
   TA_KEYPHRASEPATH=/text/analytics/v2.0/keyPhrases

   The TA_KEY value is found in the Azure portal for Text Analytics on the ** page

Current features

• Toc Manager: open the toc.yml (as the active file for the VS Code extension).
• Pass the values from Text Analytics to the contructor:

  const key=process.env.TA_KEY;
  const uri=process.env.TA_HOST;
  const route=process.env.TA_KEYPHRASEPATH;
  const textAnalyticsConfig = {key, uri, route};

• Use TocManager to find keyphrases:

  let problem = {};
  problem["text"] = markdownTextOfDocumentIncludingMetadata;
  let response = await tocManager.getKeywordsAsync(problem);

• Response is text of TOC with new metadata value for displayName of each toc entry:

  - name: LUIS Documentation
    href: index.yml
  - name: Overview
    expanded: true
    items:
    - name: What is Language Understanding?
      href: what-is-luis.md
      displayName: luis-model,LUIS model,LUIS endpoint,LUIS app

Install

npm install

Tests

Using Jest for tests. Lots of happy path, a few not-so-happy path. Tests for Index.js and TocManager.js may not run as they are generally tested via integration with VS Code extension. Test data is in the data directory. Tests are not extensive. Feel free to contribute.

Development

Developed in Typescript then compiled to ES6 Common javascript.

API

Docs are generated via npm run docs and found in the docs directory.