VHDL-LS
[FEATURE] Sub-project: vhdl_doc
For a few years now, the rust_hdl language server has provided great benefits to my colleagues and me in our FPGA design workflow. Our team is growing, and one of the pain points we're finding is adequate documentation of VHDL modules. I'm generally familiar with the Rust language and admire the documentation tooling it provides. I'm interested in starting a sub-project within rust_hdl to provide a similar documentation engine with a few goals:
- VHDL documentation is embedded in the code similarly to Rust documentation
- Generate graphic blocks for VHDL entities (similar to symbolator, which seems to be a dead project)
- Support documentation generators for common HDL patterns such as memory-mapped registers, data busses, and waveforms
My main motivation for posting here is that I envision some level of parsing support for documentation comments. Is there interest in such a tool under the rust_hdl umbrella, or would it fit better in another repository or project?
Hi @n8tlarsen
It's always great to hear that rust_hdl is being used and enjoyed by people.
I think a documentation extractor and symbol generator would be a great addition in the VHDL field - and something that is currently not available in the desired quality. Therefore, it's great to hear that you want to add such features with the help of rust_hdl. Concerning your point about integration or separation, I think that there are valid points about keeping things separated. Separation brings a high degree of individuality as well as separation of concerns. Issues or features that belong only to the documentation part would go into the separate repository. This also means that the tool is not as dependent on rust_hdl as it would be with the integrated approach.
However, I still like the idea of development under the rust_hdl umbrella better. This is mainly because in VHDL (and related languages), tools (especially good once) are scarce. Therefore, I think that efforts should be combined so that that there is one place for great tooling for VHDL.
One thing that I will mention is that there are currently efforts to rewrite the parsing part and make it available as public API - very much in the spirit of enabling projects such as the one you are talking about. However, this is still a bit in the beginning and given limited time the contributors and I have, this will likely take some time until it can serve as an API base. I'm mentioning this so that any efforts in building tools around rust_hdl try not to depend too much on the actual implementation as it is bound to change.
Just wanted to add my two cents on this.
Doxygen already supports documentation for VHDL (see the docs), so it's not far-fetched that projects out there are already using this format.
Might be source of inspiration to look what other LSPs are doing about this.
For example in C\C++, clangd has an internal Doxygen parser that can provide information described in comments when you hover on a token, but this is no easy task (see issues).
Thanks for the feedback! @Schottkyc137 How are the efforts to provide a public API progressing? I browsed through the conversation you linked as well as a short look at the new commits in your fork. It's been a few months since any new developments so I'm wondering if there's still an appetite for this public API especially since the parser needs a rework. I'm new to interacting with ASTs so I don't have a ton of opinions. As far as the vhdl_doc project is concerned, keeping comments somehow linked with their appropriate syntax elements and providing easy access to the comment string should be all that is required. It shouldn't be too hard to abstract the exact implementation of the AST API. I am curiuos how I'd go about using today's implementation to extract comment blocks. It doesn't seem like the documentation for vhdl_ls were written with a public API in mind.
After some research into static site generators and a look at Doxygen's implementation, I think using doxygen's comment style --! and /*! ... */ (VHDL2008) for noting a documentation comment seems like a reasonable approach. As Doxygen is primarily a C-like language documentation generator, many of the special commands don't make a lot of sense in VHDL. Markdown styled doc comments seem like the best option, which works in harmony with the mdBook utility to easily handle frontend presentation of the docs. Rust's documentation engine seems custom built for Rust code and a project of that magnitude is a bit outside of my appetite; leaning on existing projects for pieces of the project is key for me.
Some more cents from me - I think I've gone through a quite similar "pain point" with our codebase.
After giving several tools a try, i fell back to Doxygen. In the end I made it work for us - using several tweaks to navigate around the fact that Doxy really wasnt written with VHDL in mind..
- I'm using WaveDrom to render timing diagrams and bitfield to render register maps - they can be written in Doxy blocks using \htmlonly
- Since the default Doxy hierarchies are useless for VHDL imo, I manually define the doc structure with Doxy's grouping
- For longer descriptions, I fall back to markdown text (which is cumbersome to include into the grouping mechanism, but writing long descriptions in VHDL doxy blocks is worse)
- What my setup really lacks is a good graphical render of entities as well as state machines. For the moment I just include SVG exports from Visio where needed, but TerosHDL has good-looking tools for both of them
Maybe my "setup" is useful as inspiration. Looking forward to hear from your progress!
Hi! I recently started a bit of a personal project (not public yet), that takes an ast from rust_hdl and represents it in a block-diagram style a bit like Mentor Graphics HDL designer. It has e.g. automatic inferring of process inputs and outputs and the plan is to have much more (infer clocks, detect simple RTL constructs like Flip-Flops or MUXes while just rendering more complicated structures as either a named black-box or a VHDL expression.
It would be great to add such features like component IOs by spaced and commented groups in HDL code and many more. My ultimate dream is to have a real-time rendering on the codebase in a browser window beside the editor that can be used to navigate (think a bit like with overleaf for LaTeX or the typst online editor).
For rendering, right now I just map my "logical" structure into a graphviz format and use graphviz (with all of its downfalls). It would be really nice to have some more extensive (and potentially interactive) renderer like how Vivado visualizes block diagrams where you can easily follow signals and only draw parts of the full schematic.
Is there anyone interested in a system like this (potentially being merged into a part of vhdl_ls like the preview feature of tinymist for typst?)
My biggest motivation is that both the mentioned Vivado schematic view as well as the rendering feature that TerosHDL provides end up visualizing a generated rtl netlist instead of the behavioural VHDL (or by extension verilog) code that humans write to be both understandable by other humans as well as translatable to a netlist.
I'd certainly be interested in seeing how you set up the vhdl_lang crate to build and traverse an AST. There's not exactly a usage guide that I could find on how to set that up. I'd also love to see a screenshot of a sample rendering you've generated!