cesnet / sphinx-vhdl

SPHINX-VHDL

A sphinx domain for semi-automatically documenting VHDL

This extension for Sphinx allows you to keep your documentation in code and automatically draw it out into your main documentation using just few simple directives.

You can see the detailed documentation at https://cesnet.github.io/sphinx-vhdl/, or build it yourself (running make while in the doc directory and having sphinx + sphinx_rtd_theme installed should be sufficient)

Usage

The python package must be installed with

pip3 install sphinx-vhdl

This extension requires Python >= 3.8 and Sphinx >= 6.0.0.

Note that your documentation may use multiple sphinx extensions or an alternative theme (such as sphinx_rtd_theme), which you must also have installed.

Configuration

In your sphinx conf.py file add

extensions = ['sphinxvhdl.vhdl']
vhdl_autodoc_source_path = 'path/to/your/vhdl/sources/root'

Where is the SPHINX-VHDL extension used?

• Open FPGA Modules (OFM) by CESNET
• NDK Minimal Application by CESNET
• Do you use SPHINX-VHDL in your public VHDL repository? Please add a link to this list!

Repository maintainer

• Jakub Cabal, [email protected]
• Vladislav Válek, [email protected]

sphinx-vhdl's Issues

Entity name with underscore not working

changing the entity name to count_er and updating the *.rst file shows following error :

Exception occurred:
File "***/python3.11/site-packages/sphinxvhdl/vhdl.py", line 379, in handle_signature
self.content = self.content + StringList(['', ''] + autodoc.entities[sig.lower()])
~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
KeyError: 'count_er'

the filename is still counter.vhd.

When the Filename is changed to count_er.vhd it works.

=> Is it possible to have filename and entity name different ?

[Meta] Gathering interest in a "Framework :: Sphinx :: Domain" PyPi classifier

I'm trying to get a Framework :: Sphinx :: Domain PyPi classifier approved to help with the Sphinx docs as well as keep the ecosystem more organize and I need to demonstrate interest by having 10 or more project maintainers submit comments about their desire to use the new classifier.

If the maintainer of this project thinks a Framework :: Sphinx :: Domain would be useful for helping people find the domain as well as help the greater Sphinx ecosystem, please leave a comment on sphinx-doc/sphinx#11562 expressing interest in using the classifier with a link to the package that you maintain to help with the approval process.

Once it gets approved I can come back and submit a PR to add it to the package metadata.

Thanks!

"make latexpdf" raises KeyError: 'objtype' when using autoentity

Hi, and first of all thank you for this very promising sphinx extension!

However, I am experiencing issues while generating a latex or PDF file, both on your doc example example_built.rst and on one of my source files, and I don't understand the issue!

Exception occurred:
  File "c:\users\wolffa1\watt\cmtp\cmtp_fpga_venv\lib\site-packages\docutils\nodes.py", line 652, in __getitem__
    return self.attributes[key]
KeyError: 'objtype'

full error log
sphinx-err-68f1ammn.log

Part of my pip environment:

Sphinx==4.1.2
sphinx-vhdl==0.1.0
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5
sphinxcontrib-wavedrom==3.0.1

Possiblilty to have multilple folder or exclude folders

Hi,

is there a possibility to have multiple folder or exclude some folders?

In my project structure i have different folder where the vhdl files are.
And also some testbench files where the autodoc has some problem with.

Top
|
|--module1
| |--hdl -> good vhdl files
| |--testbench -> good vhdl files
| |--verification -> bad vhdl files
|--module2
| |--hdl ->vhdl files
| |--testbench -> good vhdl files
| |--verification -> bad vhdl files

Thx

vhdl:autoconstant / vhdl:constant

Hi, is there a reason why vhdl:autoconstant or vhdl:constant is not implemented?
Is there already a way available to document a constant?

Installation brings me previous version

Hi guys! Sorry for the inconvenience in case I can't tell that the problem occurs locally.

When I install the library from "pip install sphinx-vhdl" what happens is that it seems to be bringing version 1.4, because when I run "make html" an error appears mentioning the following:

from sphinx.directives import ObjectDescription, T

That is, "T" is not updated to "ObjDescT".

I solved this by cloning its repository and installing locally, but it doesn't help me when I want to generate documentation in my CI/CD in git.