In-Editor Help
This is everything but straight-forward. The vscode.Webview is quite restrictive; html+css is rendered correctly except for images, external links open in a new (standard) browser window, internal links to #anchors don't work at all. Also, there's no navigation panel. For links to work (i.e. open a new page), they have to call a JavaScript function which tells the extension to load a new page, which then again does that work and provides the new html source. Great. I saw myself confronted with two options:
- Try parsing the existing generated .html files, replace links with those function calls, replace image resources with the correct VSCode-scheme-URI, replace the existing header with one that provides a navigation.
- Let Makedocs spit out a more easily readable format - a decl.json containing all DocDecls - and build the contents from that.
Both methods have their pros and cons. I went down path 2 because I was too scared of parsing .html which might change and then break the parsing. Of course this means I have to transform Markdown in docs again, which wouldn't be too much of a hassle if all the Markdown was standard Markdown (I guess I'd find some existing Markdown to HTML transformer).... Also this method will break syntax-highlighting in code blocks. It could be implemented again, but for now I see things that have higher priority. Lastly this method will ignore custom global style rules like the multicolumn class, but if there's only one of them, I might even just copy that into my template. Speaking of styles, this method allows to style everything according to the currently set VSCode theme, which is nice.
So where am I now?
- A navigation panel (not fully functional now)
- The main menu is part of the .html documentation templates - There would be ways of extracting it from there, but for now I just hard-coded it. I'll adapt it to what @Phil7 will present us with
- Declaration-targeting links work. They're resolved by Makedocs directly as these resolving rules are soooo complicated*. External links work too, naturally. Anchor-links don't work yet
* just to give you a hint of what Makedocs has to deal with when resolving a link: [[Create]] might be targeting a document or any declared identifier (function, method, class, module...). How should it now? It doesn't. It first looks in the current scope (module or class depending on where the decl containing that link sits), then it looks in all imported modules, then it looks in the global scope, which possibly even finds it in documents.