f4pga / f4pga/ideas

Add a Verilog / SystemVerilog support to Sphinx

Open
#11 18 comments 7 reactions 0 assignees View on GitHub
project-symbiflow-arch-defs project-verilog-to-routing type-coding type-docs type-infra
Dominant language
No language data
Stars
86
Forks
9
PR merge metrics
No merged PRs in 30d

Description

# Add a Verilog / SystemVerilog support to [Sphinx](https://sphinx-doc.org)

# Brief explanation

We use [Sphinx](sphinx-doc.org) for documentation heavily. Sphinx currently doesn't support Verilog or SystemVerilog natively. It would be good if it did.

## Expected results

Sphinx has native support for Verilog and SystemVerilog.

# Detailed Explanation

While Sphinx was originally created for Python, it does supports the [concept of "domains"](http://www.sphinx-doc.org/en/stable/domains.html). Domains allow Sphinx to support multiple languages.

It might be useful to use the Python module [hdlparse](https://kevinpt.github.io/hdlparse/) which is used by [Symbolator](https://kevinpt.github.io/symbolator/) to generate nice diagrams. [Symbolator](https://kevinpt.github.io/symbolator/) already has some [Sphinx integration](https://kevinpt.github.io/symbolator/#sphinx-extension);
```sphinx
.. symbolator::

component foo is
...
end component;
```

The current planned process for getting Verilog into Sphinx is the following;
1. Use [doxygen-verilog](https://github.com/avelure/doxygen-verilog) to generate Doxygen output from the Verilog
2. Use [breathe](https://breathe.readthedocs.io/en/latest/) and/or [exhale](http://exhale.readthedocs.io/en/latest/usage.html) to read the Doxygen output into Sphinx.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.