overview documentation of the extension (#857)

* WIP documentation of how VE communicates with HOST and LSP

* Move Quarto interface next to where it is init'd

* Move command registrations in to `activate`

* Make Providers in hooks uniform

* document `defaultExtensionHost` and move `createPreviewPanel`

* Add documentation to help with understanding and navigating

* Fix `provideStatementChange` refactor

* Fix references to `Quarto` type, add comment

* Clarify diagnostics "for YAML" in overview.md

Co-authored-by: Julia Silge <[email protected]>

* Add diagram

---------

Co-authored-by: Julia Silge <[email protected]>

Author: vezwork

apps/lsp/src/custom.ts

@@ -31,7 +31,8 @@ import { Hover, Position, TextDocuments } from "vscode-languageserver";
 import { CodeViewCellContext, CodeViewCompletionContext, kCodeViewAssist, kCodeViewGetDiagnostics, kCodeViewGetCompletions, LintItem } from "editor-types";
 import { yamlCompletions } from "./service/providers/completion/completion-yaml";
 import { yamlHover } from "./service/providers/hover/hover-yaml";
-import { EditorContext, Quarto, codeEditorContext } from "./service/quarto";
+import { EditorContext, codeEditorContext } from "./service/quarto";
+import { Quarto } from "./quarto";
 
 export function registerCustomMethods(
   quarto: Quarto,

apps/lsp/src/index.ts

@@ -257,6 +257,7 @@ connection.onInitialized(async () => {
   const parser = markdownitParser();
 
   // create language service
+  // note that `mdLs` is referenced in `connection.onInitialize` above
   mdLs = createLanguageService({
     config,
     quarto,

apps/lsp/src/quarto.ts

@@ -31,7 +31,6 @@ import {
 import { QuartoContext } from "quarto-core";
 
 import {
-  Quarto,
   CompletionResult,
   EditorContext,
   HoverResult,
@@ -42,6 +41,16 @@ import {
 } from "./service/quarto";
 import { LintItem } from "editor-types";
 
+export interface Quarto extends QuartoContext {
+  getYamlCompletions(context: EditorContext): Promise<CompletionResult>;
+  getAttrCompletions(
+    token: AttrToken,
+    context: EditorContext
+  ): Promise<CompletionItem[]>;
+  getYamlDiagnostics(context: EditorContext): Promise<LintItem[]>;
+  getHover?: (context: EditorContext) => Promise<HoverResult | null>;
+}
+
 export async function initializeQuarto(context: QuartoContext): Promise<Quarto> {
   const quartoModule = await initializeQuartoYamlModule(context.resourcePath) as QuartoYamlModule;
   return {

apps/lsp/src/service/index.ts

@@ -17,7 +17,7 @@
 import type { CancellationToken, CompletionContext, TextDocuments } from 'vscode-languageserver';
 import * as lsp from 'vscode-languageserver-types';
 import { URI } from 'vscode-uri';
-import { Document, Parser } from "quarto-core"
+import { Document, Parser } from "quarto-core";
 import { LsConfiguration } from './config';
 import { MdDefinitionProvider } from './providers/definitions';
 import { DiagnosticComputer, DiagnosticOnSaveComputer, DiagnosticOptions, DiagnosticsManager, IPullDiagnosticsManager } from './providers/diagnostics';
@@ -33,7 +33,7 @@ import { MdTableOfContentsProvider } from './toc';
 import { isWorkspaceWithFileWatching, IWorkspace } from './workspace';
 import { MdHoverProvider } from './providers/hover/hover';
 import { MdCompletionProvider } from './providers/completion/completion';
-import { Quarto } from './quarto';
+import { Quarto } from '../quarto';
 
 export { IncludeWorkspaceHeaderCompletions } from './providers/completion/completion';
 export type { MdCompletionProvider } from './providers/completion/completion';
@@ -44,7 +44,7 @@ export { DiagnosticCode, DiagnosticLevel } from './providers/diagnostics';
 export type { ResolvedDocumentLinkTarget } from './providers/document-links';
 export type { ILogger } from './logging';
 export { LogLevel } from './logging';
-export type { ISlugifier } from './slugify'
+export type { ISlugifier } from './slugify';
 export { Slug, pandocSlugifier } from './slugify';
 export type { ContainingDocumentContext, FileStat, FileWatcherOptions, IFileSystemWatcher, IWorkspace, IWorkspaceWithWatching } from './workspace';
 
@@ -84,7 +84,7 @@ export interface IMdLanguageService {
    *
    * @returns The headers and optionally also the link definitions in the file
    */
-  getDocumentSymbols(document: Document, options: { readonly includeLinkDefinitions?: boolean }, token: CancellationToken): Promise<lsp.DocumentSymbol[]>;
+  getDocumentSymbols(document: Document, options: { readonly includeLinkDefinitions?: boolean; }, token: CancellationToken): Promise<lsp.DocumentSymbol[]>;
 
   /**
    * Get the folding ranges of a markdown file.
@@ -238,7 +238,7 @@ export function createLanguageService(init: LanguageServiceInitialization): IMdL
       return documentHighlightProvider.getDocumentHighlights(document, position, token);
     },
     computeOnSaveDiagnostics: async (doc: Document) => {
-      return (await diagnosticOnSaveComputer.compute(doc))
+      return (await diagnosticOnSaveComputer.compute(doc));
     },
     computeDiagnostics: async (doc: Document, options: DiagnosticOptions, token: CancellationToken): Promise<lsp.Diagnostic[]> => {
       return (await diagnosticsComputer.compute(doc, options, token))?.diagnostics;

apps/lsp/src/service/providers/completion/completion-attrs.ts

@@ -13,7 +13,8 @@
  *
  */
 
-import { AttrContext, AttrToken, EditorContext, Quarto } from "../../quarto";
+import { AttrContext, AttrToken, EditorContext } from "../../quarto";
+import { Quarto } from "../../../quarto";
 
 export async function attrCompletions(quarto: Quarto, context: EditorContext) {
 

apps/lsp/src/service/providers/completion/completion-yaml.ts

@@ -25,7 +25,8 @@ import {
 } from "vscode-languageserver-types";
 
 
-import { EditorContext, Quarto } from "../../quarto";
+import { EditorContext } from "../../quarto";
+import { Quarto } from "../../../quarto";
 
 export async function yamlCompletions(quarto: Quarto, context: EditorContext, stripPadding: boolean) {
 
@@ -67,7 +68,7 @@ export async function yamlCompletions(quarto: Quarto, context: EditorContext, st
               .replace(/(<([^>]+)>)/gi, "")
               .replace(/\n/g, " ")
           )
-        }
+        };
       }
 
       // strip padding if requested (vscode doesn't seem to need indentation padding)

apps/lsp/src/service/providers/completion/completion.ts

@@ -23,7 +23,7 @@ import {
   CompletionTriggerKind,
   TextDocuments
 } from "vscode-languageserver";
-import { Quarto } from "../../quarto";
+import { Quarto } from "../../../quarto";
 import { attrCompletions } from "./completion-attrs";
 import { latexCompletions } from "./completion-latex";
 import { yamlCompletions } from "./completion-yaml";

apps/lsp/src/service/providers/completion/refs/completion-biblio.ts

@@ -21,7 +21,7 @@ import {
 import { cslRefs } from "editor-server";
 
 import { Document, Parser, filePathForDoc, documentFrontMatter } from "quarto-core";
-import { Quarto } from "../../../quarto";
+import { Quarto } from "../../../../quarto";
 
 export async function biblioCompletions(
   quarto: Quarto,

apps/lsp/src/service/providers/completion/refs/completion-crossref.ts

@@ -23,7 +23,7 @@ import {
 import { XRef } from "editor-types";
 
 import { EditorServerDocuments, xrefsForFile } from "editor-server";
-import { Quarto } from "../../../quarto";
+import { Quarto } from "../../../../quarto";
 
 export async function crossrefCompletions(
   quarto: Quarto,

apps/lsp/src/service/providers/completion/refs/completion-refs.ts

@@ -18,7 +18,8 @@ import { Range, Position } from "vscode-languageserver-types";
 import { CompletionItem, TextDocuments } from "vscode-languageserver";
 import { bypassRefIntelligence } from "../../../util/refs";
 
-import { EditorContext, Quarto } from "../../../quarto";
+import { EditorContext } from "../../../quarto";
+import { Quarto } from "../../../../quarto";
 import { projectDirForDocument, filePathForDoc, Document, Parser } from "quarto-core";
 import { biblioCompletions } from "./completion-biblio";
 import { crossrefCompletions } from "./completion-crossref";