New VSCode plugin for Stan

Hello!

Stan users who use VSCode are probably familiar with stan-vscode by ivan-bocharov. I recently published an updated version of this extension called vscode-stan-extension

In addition to the features of the original stan-vscode (syntax highlighting, code folding, snippets) this also features the ability to automatically format .stan files and will give you feedback in the form of the classic red/yellow squiggles to let you know about compiler errors and warnings in your code.

14 Likes

Working fantastically well so far!

One question, is there a way to support .stanfunctions files? Currently it displays a linter error due to the lack of stan blocks:

2 Likes

Yeah that should be possible! Slipped my mind, but I think I the right thing to do there is register .stanfunctions as its own “language” rather than at the moment where the plugin can’t tell them from Stan files

1 Like

This looks great! Are you planning to also add the autocompletion for the Stan functions name ?

1 Like

This is awesome. I’ve dreamed for this for ages. Now super happy for making the switch to vscode a few months ago :D It will help my workflow a lot.

I second the request for function completion :) seem the syntax highlighter is already aware of built-in functions because it colors them if they match, but full autocomplete will be great.

Second request would be contextual help information - hovering over a stan function should show the documentation for it (as it happens for R in vscode).

Adding these two features would be a drastic quality of life improvement when coding stan models.

1 Like

I think I know how to do autocomplete. Hover-over documentation is harder , since we don’t have an immediate mapping from the function name to a documentation link, as far as I know. I might be able to figure out something clever I haven’t thought of yet.

2 Likes

Ah, I hadn’t realized that the documentation just lives inside the markdown files that generate the website. Not sure if it’s worth the effort, but in principle you can create a separate .md file for each function with the content currently presented in the function reference, and then just embed those files in the larger .qmd files that collect related functions. The .md files can be named after the function and all live in a single folder. Then a hover function can reference those. Just an idea - might be too much effort to be worth it. But I know if the option magically existed today, I would love using it.

I see that for the core C++ stan math library the documentation is written with doxygen and documentation for individual functions is available. Can this be leveraged? I know that this is documetnation for the C++ usage, but the function names match, right, so maybe the necessary things could be extracted?

E.g. you have this documentation of cholesky_decompose(): Stan Math Library: stan::math::opencl::cholesky_decompose

Which almost matches the description of the stan website:


Another idea is to generate a dictionary with function names and the links that are constructed for the function_index on the website: docs/gen_index.py at master · stan-dev/docs · GitHub so on hover you could get a link to the relevant documentation section

Unfortunately the gen_index idea wouldn’t quite work, because the index links are based on the signatures we use in the docs, which don’t line up 100% with what the compiler uses when it comes to certain shorthands (like abs is written in the docs as abs(T), rather than listing all the types it accepts).

I like the idea of splitting out individual markdown files in the docs to be honest, but it would be a lot of work.

One alternative which would be easy but not the most helpful is linking you to the correct section in the index - you’d need to then click again to get to your actual doc page, but it would be faster than searching I guess?

Yes, the last option could be a decent intermediate solution - definitely faster than searching.

Long term splitting the function docs could nice for many reasons like this when you might suddenly want to use documentation for multiple purposes.

1 Like

I’ve just published 0.7.0 which has better support for stanfunctions files:

  • linting should work
  • formatting should work
  • things like generated quantities { in a .stanfunctions file will no longer be highlighted

I also added support for highlighting inside triple-backtick-quoted ```stan blocks inside markdown files.

Going to look into completion/hover-text later today.

1 Like

Thanks, much appreciated!

I’ve just published 0.8.0, featuring:

built-in function and distribution completion:

preview

hover-over text for built in functions with a link to the documentation and a list of known signatures:

preview

7 Likes

Kind of side question but are those features implemented in RStudio?

Back in 2018, it was announced in this blog post from the posit team that new stan related features would be implemented in Rstudio v1.2. I recently updated my Rstudio and I should be up to date on the latest features but things like stan autocompletion and document outline are not working. I can’t find any info online as to why it wouldn’t have been implemented by now so I’m wondering if it’s a problem on my end.

I’ve just pushed 0.8.1 which features a visual tweak to the hover-over text and a few minor improvements to the highlighting logic and snippets.

The above preview now looks like

preview

This is the last change I am currently planning on making for now unless the documentation changes @Ven_Popov suggested come to pass, in which case I will overhaul the hovering again. There are a few internal changes in stanc that would improve some things I might look into soon.

4 Likes

I have just published version 0.9.0 of the extension.
This uses the hot-off-the-presses support for #include statements in stanc.js to support formatting and linting of files that contain #includes of other files in the same folder or VSCode workspace.
It also contains some fixes for how #includes are highlighted.

I suspect the next release will likely just be a version bump to 1.0.0 if everything is stable after a week or so

2 Likes

The extension is now available on open-vsx, which means users of other Code-based IDEs like VSCodium or Rstudio/Posit’s new “Positron” should be able to use it

6 Likes

Works great! Thanks A lot

3 Likes