Installation and Use

[radonnachie]

Good day, again I am excited by your work.

I have forked, and then sys.path.appended the directory to the top of the sphinx config.py with the inclusion in extensions as 'sphinx_vhdl.vhdl'....

Obviously seems like I am missing a valid installation step as no such module is found..

Any hints?

[radonnachie]

I see that there is no actual content to any of the files, and that this is a place holder repo.

[bradleyharden]

@RocketRoss, that's correct. This would be a big project. In a world where I had more time, I would work on it, but that's not reality for me right now. I did some reading of the Sphinx source a while back, to understand how difficult it would be. I put together some thoughts and questions in #4. If you're interested, would you have a look and add your thoughts?

[Paebbels]

@RocketRoss yes, this is a placeholder repo, because work is still delayed. One prerequirement is to parse and understand VHDL. Therefore I creates pyVHDLParser and other related Python projects.

[oholimoli]

Why do you need to develop a VHDL parser? Is the support of Doxygen for VHDL not good enough? Gruss nach Bötzingen ;)

[bradleyharden]

Hi @oholimoli. Are you trying to provide some sort of constructive suggestion? I don't really understand the purpose of your comment.

[oholimoli]

Sorry for the unclear question. I was redirected to this issue from here: breathe-doc/breathe#519

Since the goal of this project is VHDL support in Sphinx, I was wondering if it would be possible to achieve this goal by implementing a doxygenvhdlentity, doxygenvhdlcomponent function into the breathe project.

But you are right.. seems to be the wrong place for this question. Please feel free to delete my comment.

[bradleyharden]

Ah, ok, I understand. I actually hadn't heard of breathe. It's an interesting alternative. I have no idea what that would take though.

What I would really like to do is adapt rust_hdl to support comments and use it as a front-end, mostly because I like Rust. Breathe might be a model there of how you transfer things into Sphinx.

But all of this is moot, because there isn't anywhere near enough time in life 😩

[umarcor]

@oholimoli I think that your initial questions were pertinent, although too brief. A VHDL parser needs to be developed because Doxygen's VHDL parser supports a limited subset of the language only. It allows documenting functions, entities and architectures, but AFAIAA it does not look deeper into de architectures, and it does not handle VHDL 2008 features.
There are several projects trying to provide ready to use solutions with minimal functionality, by accepting the limitations of reusing tools designed for other languages. Conversely, this project, pyVHDLParser and pyVHDLModel are expected to support all the language features and be limited by Sphinx only.

By the way, @Paebbels, is VHDL/sphinx-vhdl a placeholder for this same repo?

What I would really like to do is adapt rust_hdl to support comments and use it as a front-end, mostly because I like Rust. Breathe might be a model there of how you transfer things into Sphinx.

@bradleyharden I think it would be interesting for rust_hdl to target pyVHDLModel, similarly to GHDL. Then, a pyVHDLModel -> Sphinx tool would work regardless of the frontend/backend used for parsing.

[Paebbels]

This repo is meant to provide the Sphinx VHDL language domain. So a Sphinx extension that adds documentation capabilities to Sphinx for VHDL like Sphinx naturally provides Python and C domains.

[bradleyharden]

@umarcor, I didn't realize GHDL had a Python API. Does GHDL store comments in the AST? Could it be used instead of rust_hdl?

[bradleyharden]

By the way, to be fair to Doxygen, it looks like it does handle VHDL-2008 block comments.

https://www.doxygen.nl/manual/docblocks.html#vhdlblocks

[umarcor]

I didn't realize GHDL had a Python API.

@bradleyharden, it's rather new, but you are familiar with most of it. In December-January, Patrick split pyVHDLModel from his pyVHDLParser. We reworked GHDL's Python features and grouped them in pyGHDL. It included pyGHDL.libghdl (wrapper around the shared lib), pyGHDL.lsp (language server) and pyGHDL.dom (DOM). That last one is the "binding" for using GHDL's libghdl shared library as a backend for pyVHDLModel. So, now we can use GHDL and pyGHDL for obtaining a Syntax Model of the sources.

In June-July, Patrick has been completing the binding, and I've prototyped using it for a GUI: https://umarcor.github.io/osvb/apis/project.html#open-source-vhdl-design-explorer-osvde (you will find a better explanation and references in there)

Does GHDL store comments in the AST? Could it be used instead of rust_hdl?

pyGHDL does not preserve the comments yet, because GHDL itself does not. However, that's something we want to enhance, precisely because it is useful in the context of pyVHDLModel.

With regard to rust_hdl, I believe it would be interesting to have it supported as another backend in pyVHDLModel. Then, whatever funcionality we implement on top of pyVHDLModel would work regardless of the backend (ghdl-ada, rust_hdl-rust or pyvhdlparser-python). I do understand that rust_hdl users might want to avoid Python, however, when targeting Sphinx that is a dependency already.

By the way, to be fair to Doxygen, it looks like it does handle VHDL-2008 block comments.

That is correct. I should have said that Doxygen supports some VHDL 2008 features only. The main advantage of pyVHDLModel is that it parses the whole document (including the content of the architecture, concurrent statements -blocks, processes, generates, instantiations...). It is not limited to the entity ports/generics and the architecture as a box. So, pyVHDLModel is not for documentation only, but for anything you might want to do on the sources (based on parsing, without analysis or elaboration).

Apart from having an Sphinx domain, another feature we want to build on top of pyVHDLModel is a source formatter (see a demo in https://github.com/ghdl/ghdl/blob/master/pyGHDL/dom/formatting/prettyprint.py). In order to spit out the formatted sources, we do need to preserve the comments.

EDIT

BTW, we are considering using pyVHDLModel as an alternative parser for VUnit. We will implement dependency scanning features on top of pyVHDLModel, so that VUnit can reuse the parsing capabilities of GHDL/pyVHDLParse/rust_hdl, instead of using an internal feature-limited parser. The challenge is that we don't want to make GHDL a compulsory dependency (yet) and pyVHDLParser is not ready-to-use (yet).

[bradleyharden]

another feature we want to build on top of pyVHDLModel is a source formatter

Have you seen vhdl-style-guide? I've never used it, but I remember looking through the documentation and thinking it would cover most any use case.

we are considering using pyVHDLModel as an alternative parser for VUnit

I like this idea, given the limitations of the VUnit parser. The dependency problem is big, though. My first instinct would be to stick with pyVHDLParse, since it's Python. But it might be fairly slow, especially for large repositories. I don't particularly like the idea of a full GHDL dependency. A dependency on Rust for rust_hdl also isn't great. But there, you might be able to implement it as a pre-compiled, static binary. Just an idea.

[umarcor]

Have you seen vhdl-style-guide? I've never used it, but I remember looking through the documentation and thinking it would cover most any use case.

Yes. Precisely, the idea of pyVHDLModel is that it can replace the parsers in several open source VHDL tooling projects written in Python:

• vhdl-style-guide
• Symbolator
• VUnit
• TerosHDL (partially)
• VHDLTool

See https://umarcor.github.io/osvb/apis/project.html#future-work and https://github.com/jeremiah-c-leary/vhdl-style-guide/issues?q=pyVHDLParser

I like this idea, given the limitations of the VUnit parser. The dependency problem is big, though. My first instinct would be to stick with pyVHDLParse, since it's Python. But it might be fairly slow, especially for large repositories. I don't particularly like the idea of a full GHDL dependency. A dependency on Rust for rust_hdl also isn't great. But there, you might be able to implement it as a pre-compiled, static binary. Just an idea.

Exactly. The instinct is to wait until pyVHDLParser is available, so that we can replace it transparently without any additional "compiled" dependency. VUnit is a Python only project, which makes it much easier to distribute than, e.g., cocotb. That's why I described using pyVHDLModel + pyGHDL as an "alternative" but not a replacement (yet).

However, in the mid term I'm good with assuming that GHDL is a must-have dependency for any VHDL developer. So, I'm personally ok with a VUnit bundle that requires GHDL.

I don't think that rust_hdl is very useful compared to GHDL in the case of VUnit. It's true that it can be more easily distributed because it can be statically compiled. However, it's a parser only, while GHDL is a complete simulator and a synthesizer. Therefore, as a user I am willing to have Python only or a complete bundle, rather than an intermediate solution. Nonetheless, we discussed this with @kraigher some time ago: VUnit/vunit#529 (comment)

[bradleyharden]

For a native installation, I don't really have a problem with a hard GHDL dependency. But it's a bit of a pain inside containers. It's not a total deal breaker, but it does represent significant bloat to VUnit just to get a slightly better parser. Given that I've never actually had a problem with VUnit's parser, I would probably prefer the status quo.

[umarcor]

Agree. For the container issue, I believe the solution is to provide a CLI execution abstraction layer which supports running either locally or inside a container in a way transparent for the abstraction layers on top. So, VUnit's runner would use that CLI abstraction instead of calling the tools directly.

• pyCLIAbstraction is to be split from pyIPCMI.
• edalize and pyFPGA/openflow provide wrappers for running tools locally or using containers from hdl/containers (see https://hdl.github.io/containers/ug/index.html#_fine_grained_pulling).

Nonetheless, this is a mid term goal and it's off-topic in this issue 😆 .

[Paebbels]

Beginning of 2023, I was to create:

A Dependency Diagram	An Instantiation Diagram	A Compile Order Diagram

It was reading sources with GHDL (libghdl.dll/.so + pyGHDL.dom + pyVHDLModel) and producing these diagrams as GraphML. Rendering was done with yEd.

I then reactivated that repository, which was all them time a place holder. The current proof-of-concept work creates some auto generated documents nodes in Sphinx/docutils.

Here is a screenshot:

Auto Generated Documentation