Team DevLog Holzchopf - Update 2020/07/01

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
Wow, already a month went by. Here is a short update on what I am doing. @Phil7 and @Holzchopf can do similar if they want to.
Well, of course! Here we are. I start a new thread, to keep your dev log tidy ;)

As you might have read, I am currently working on a VS Code extension for Cerberus X. What I have so far:
- syntax highlighting
- document outline
- rudimentary in-editor help panel

See for yourself:
20200625-vscode_outline.png


It's not yet usable, as there's no build option yet. But you know, the whole thing started as an experiment and my primary focus was on whether an extension could provide an outline and in-editor help panel. Latter isn't nice to look at yet (and turned out to be a massive pain in the rear thanks to (valid) security restrictions), but you can tell that a proper VS Code extension for Cerberus X is in its making.
 
Last edited:

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
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:
  1. 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.
  2. 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?

20200701-vscode_documentation.png


  1. A navigation panel (not fully functional now)
  2. 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
  3. 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.
 

MikeHart

Administrator
Joined
Jun 19, 2017
Location
Germany
I am all for moving to a standard format. Rich provided a conversion tool, so we could settle for .md for all the official stuff.
 

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
I just had the following idea: Instead of passing raw .cerberusdoc content to the extension, I could parse the markdown directly within Makedocs and put the result in the output .json - then we'd only have one tool that has to deal with this kind of markdown, namely Makedocs. This way the generated html does not change when templates change and also if we ever change the markdown format it will only be Makedocs that has to be updated.

I'll try that now and report back.
 
Top Bottom