I want to document a module (in this case, https://github.com/lowRISC/ibex/blob/master/rtl/ibex_core.sv). This module has a fair amount of ports and parameters, the current documentation can be found at https://ibex-core.readthedocs.io/en/latest/integration.html.

When trying sphinx-verilog-domain, I found a couple issues:

• Nesting parameters and ports under the :verilog:module directive doesn't allow for sections and other content in between ports and parameters, e.g. to group parameters into logical groups. For example, that's how a section of documentation could look:

   Security-related signals
   ~~~~~~~~~~~~~~~~~~~~~~~~
   
   Ibex' security features can detect various security-related problems and produce alerts.
   Refer to the :ref:`security` section for details.
   
   .. verilog:port:: output logic alert_minor_o
   
     Core has detected a fault which it can safely recover from.
     Can be used by a system to log errors over time and detect tampering / attack.
     This signal is a pulse, one cycle per alert.
   
   .. verilog:port:: output logic alert_major_o
   
     Core has detected a fault which cannot be recovered from.
     Can be used by a system to reset the core and possibly take other remedial action.
     This signal is a pulse, but might be set for multiple cycles per alert.

  I see the similarity of parameters/ports in Verilog to function arguments in other languages, but it's not quite the same: a typical function in C or Python has perhaps a handful of arguments, while a Verilog module can easily have dozens of parameters and ports. So a solution which deviates from the way functions/methods are described in other languages seems reasonable.

• :verilog:module requires the whole module signature. Providing this signature duplicates the information that is available further down in the port and parameter directives (that's the same for other Sphinx domains normally), but in contrast to other languages, the module parameter/port list is rather long (easily 100s of lines).

I'm not sure what the right solution in line with other Sphinx domains would be. I can see two options:

• Either, go for something like :py:module, which makes all subsequent directives be in that module.
• Or, provide a way to give a "fully qualified" name as port name, which is then stripped out; e.g. :verilog:port:: ibex_core.alert_minor_o to describe the port alert_minor_o of the module ibex_core.

Not strictly related, but kind of related: specifying the :verilog:module directive without parameters/ports would be very helpful.