Docfx: @ intellisense support in our vscode extension

[vicancy]

1. Invoke condition
   The opened file must be inside a workspace where docfx.json exists

2. Behavior:
   When xref syntax (@, <xref:) is typed, invoke the intellisense to provide available uids

3. Logic

   1. Real time (schema required, @tintoy 's extension, supported types from: conceptual + mref, unsupported types: universal document processor, REST api)
   2. The generated xrefmap.yml is used for internal xref intellisense
   3. Use definitions of xref, xrefservice in docfx.json for external xref intellisense

[tintoy]

I was going to implement a symbol provider and definition provider for this in my extension; do you think they'd be useful, too?

[tintoy]

If so, I'll wait till after contributing what I've got.

[tintoy]

BTW, I currently don't do this as a completion provider (I just do it as a quick-pick list that then inserts at cursor) because for that you need to write a language server (which is doable but at the cost of a fair bit more complexity). Fortunately VSCode does provide the vscode-textmate module which can turn the MarkDown grammar used for syntax highlighting into a tokeniser.

[tintoy]

(have been doing some research on this over the weekend; it's achievable but non-trivial)

[tintoy]

Actually, you don't need a language server for the completion stuff, only if you want more sophisticated features like hovering on a UID to show info about the linked topic.

[hechaochao]

In order to implement code completion and other feature there are two approach one is implementing provider directly through provided api by vscode, another is through language server which is run in a separate process.According to docs, if inferred costly operation then language server is recommended.
So to this point, what i am working on is providing code completion for external xref which was stored on server side.Any suggestions will appreciated. BTW what you do is very cool which relate to my work and these maybe mutual complementation.thanks. @tintoy

[tintoy]

Turns out it was pretty easy to implement...

Looking forward to contributing this stuff so others can use it :)

[tintoy]

@hechaochao Oops! Sorry, I didn't realise you were working on that as well - I guess we have 2 implementations we can learn from then :)

[hechaochao]

@tintoy It doesn't matter, I have implemented it in the form of language server because i need send http request to server side.

[vwxyzh]

I think they are different, one resolves uid in other web site, one resolves uid in local work space.

[tintoy]

@hechaochao would you mind posting a link to the branch with your work? I'd be interested to see what we have in common :-)

FWIW, here's mine:

• Completion provider
  Retrieves the UIDs from the metadata cache, filtering down to anything already typed by the user.
• Metadata cache
  Populated via an Observable that receives a notification for each added / updated / removed file in the project.
• Project parser
  Going to move this out into a separate module (published via NPM); I'm in the process of merging all the related functions into a DocFXProject class that will encapsulate all project-related functionality.

[hechaochao]

@tintoy I'm a newbie to vscode extension devolpment, at now based on the official demo I have completed two feature,one is code completion when user types a string starts with like '@' then a pickup-list will be given which is a result from my server side, anther is highlighting specific words which start with like '@'.Considering what i have done is not complete and also i have not integrated it with VscPreviewExtension, so once i have improved it then i will send a pull request.Thanks to your share

[tintoy]

Ok, I've extracted the logic for working with DocFX projects and topics into a module on NPM. Once I've refactored my extension to reuse this functionality, I'll submit a PR to you guys and we can discuss what (if anything) would be useful for you to reuse. How does that sound?

PS. I have a couple of people who want to use my extension right now, so I'm going to be temporarily publishing it into the VS marketplace but will be unpublishing / pointing to your extension once it has the same functionality.

[tintoy]

Ok - my extension now uses the external module for DocFX project / file parsing. I'll start working up a PR so we can discuss.

[tintoy]

I also added a link provider for inline and XRef-style links:

https://github.com/tintoy/docfx-assistant/blob/master/src/providers/uid-link.ts

[tintoy]

@hechaochao - ok, I've completely decoupled the project parser and metadata from my extension and they now live on NPM (https://www.npmjs.com/package/docfx-project). They also have tests (even the change-notification stuff which is tricky to test).

If you have a spare 5 or 10 minutes would you mind having a glance at the module (https://github.com/tintoy/docfx-project) to see how much overlap there is with what you've been working on?

[tintoy]

If it helps, you can find class docs here, here, and here.

[tintoy]

You can find the start of a language server implementation for another extension I'm working on here (feel free to use anything that proves useful - it's based on the framework from OmniSharp). Might be worth using it to call the DocFX assemblies to parse the project?

[bitbonk]

It would be very cool to have intellisense also for regular links to other markdown files [see here](foo/bar.md) and also to anchors within the file [see here](foo/bar.md#some-header-in-that-file).
Especially the anchor intellisense would be very helpful, because getting them right is a real pain.

[tintoy]

That's a nice idea - I just built something similar for another extension; I'll see if there is anything helpful I can share :)

[tintoy]

Hmm - looks like the docfx markdown parser stores line number but not column number. That'll make it tricky to use when building a language service...

[vwxyzh]

@tintoy , docfx markdown parser replace some characters before parsing, so column number is incorrect in some case.

[tintoy]

Yeah I figured as much - the markdig parser may do the trick though - I ran
some experiments yesterday and they look promising :)

On Fri, 18 Aug. 2017, 1:44 pm .V., [e-mail] wrote:

@tintoy https://github.com/tintoy , docfx markdown parser replace some
characters before parsing, so column number is incorrect in some case.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/dotnet/docfx/issues/1933#issuecomment-323251710, or mute
the thread
https://github.com/notifications/unsubscribe-auth/ABkezJChH23jmA9gdqG65Ypasa4J_YQDks5sZQi3gaJpZM4Ou86Y
.

[vwxyzh]

@tintoy here is Markdig engine for DocFX, it is not ready for now, but it works for most case (include, code snippet, and other extensions).

[tintoy]

That's brilliant! Nice work :)

[tintoy]

I'm going to have a play with that over the weekend. Exciting!

[hechaochao]

@tintoy hi tintoy, I have implemented code completion, highlight special words and document link and also have integrated it into docfx extension.But there exist some errors that node_modules under src/servers/xrefIntellisense conflicts with node_modules under VscExtension, another error is when i package this extension through running build.ps1 under root, there occurred exception. So if you want to have a try you should download the project and debug despite errors exist.
Here is my extension https://github.com/hechaochao/docfx/tree/extension/tools/VscExtension/src/servers/xrefIntellisenseServer
and server project is here https://github.com/hechaochao/docfx/tree/fixa/tools/XRefService

Some details you can have a look at readme under src/servers/xrefIntellisense, you can add "xrefService":["http://xrefService.azurewebsites.net/intellisense/"] in docfx.json have a try.
Any suggestions will be appreciated.

[tintoy]

This is amazing - great work, will give it a look over the weekend :)

[tintoy]

I could be wrong, but from memory if a directory has a package.json (and, therefore, a node_modules directory), it should not be inside another directory that also has a package.json. You'll probably want to move it to have the same parent directory as the extension.

This is the bit that installs the server into the extension, and it may have issues if that's a parent directory:

https://github.com/hechaochao/docfx/blob/8310854829678150fafae94752c24f1b3dfd9aa4/tools/VscExtension/src/servers/xrefIntellisenseServer/package.json#L21-L22

[hechaochao]

@tintoy Yes, but if do so i need put it under 'tools' folder on the same level as VscExtension.The language-server demo is doing that like you say, but put what i added into docfx extension as subdirectory seems like a rational simple approach.Is there some solution can resolve this problem? if you delete node_modules under src/servers/xrefIntellisense then errors disappeared, but this is not a good method when being in the development process.

if the reason is as what you say, why node_modules under server doesn't confilct with the outer.
Thanks in advance.

[tintoy]

@hechaochao hey, sorry, been working on other stuff so I haven't had much time to look at the language service stuff.

Would it make life easier if you could build your language service in C#? That way you could just use the DocFX libraries rather than having to reimplement everything. I have done this for other VSCode extensions so there's plenty code I could share with you if you're interested.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[superyyrrzz]

The plugin is moved to https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-markdown