sphinx-vhdl

sphinx-vhdl is a Sphinx extension to generate documentation for the VHDL language. It can be used both to manually write your documentation, describing different language constructs used, and to automatically pull your documentation from source code comments.

Usage

To setup sphinx-vhdl for your project, please edit your sphinx conf.py file to include the following - an include of the actual module, and (optionally) a configuration of path to use for the autodoc feature doc/conf.py

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

See Configuration options for more information.

Recognized directives

Directive

Description

vhdl:autoentity

Automatic documentation of entity.

vhdl:autoenum

Automatic documentation of enumeration types.

vhdl:autofunction

Automatic documentation of functions.

vhdl:autogenerics

Automatic documentation of generics.

vhdl:autoconstants

Automatic documentation of constants.

vhdl:autopackage

Automatic documentation of package.

vhdl:autoports

Automatic documentation of ports.

vhdl:autorecord

Automatic documentation of record types.

vhdl:autotype

Automatic documentation of general types.

vhdl:entity

A single entity.

vhdl:enum

Enumeration-defined type.

vhdl:enumval

A single value in vhdl:enum.

vhdl:function

A pure function.

vhdl:generics

Generics of an vhdl:entity.

vhdl:constants

Constants of an VHDL architecture.

vhdl:package

A whole single package.

vhdl:parameters

A parameter list to a subprogram.

vhdl:ports

Ports of an vhdl:entity.

vhdl:record

Record-defined type.

vhdl:recordelem

A single field in vhdl:record

vhdl:type

A type other than a record or enumeration.

See Directives for more information.

Recognized roles

Role

Description

vhdl:entity

References vhdl:entity.

vhdl:genconstant

References individual constants in vhdl:generics.

vhdl:portsignal

References individual ports in vhdl:ports.

vhdl:type

References vhdl:enum.

See Roles for more information.

Example of VHDL code written for auto documentation

library ieee;
use ieee.numeric_std.all;

-- This package provides basic mathematic functions utilised all through
-- the design
package math_pack is
    -- This function calculates the base 2 logarithm of a number.
    --
    -- .. vhdl:parameters:: log2
    --
    --     a : in unsigned
    --         The number of which to calculate the logarithm
    function log2 parameter (a : unsigned) return integer;
end package math_pack;

library ieee;
use work.math_pack.all;
use ieee.std_logic_1164.all;

-- This is a simple counter entity that counts the amount of passed input
-- clock cycles up to :vhdl:genconstant:`max_value <counter.max_value>`.
entity counter is
generic (
    -- Determines how many clock cycles must pass before the buffer
    -- overflowing.
    constant max_value : integer := 16
);
port (
    IN_EN  : in std_logic;                                       -- The input clock
    OUT_EN : out std_logic_vector(log2(max_value) - 1 downto 0)  -- The output signal
);
end entity counter;

To use the automatically extracted comments in your documentation, you then have to place one of the auto… directives above on the relevant place in your documentation files. See Example Documentation for how this code will look when built.

.. _example_doc:

 Example Documentation
 =====================

 .. vhdl:autopackage:: math_pack

   .. vhdl:autofunction:: log2

 .. vhdl:autoentity:: counter

See Autodoc Usage for more information.

Indices and tables