XML 2 Docs

XML2Docs is a Python utility which provides the automatic generation of reStructuredText documentation for XML2VHDL defined memory maps.

The docs are generated in the generated/xml2docs folder, linked in a hierarchical format based on ICs.

Setup

XML2Docs can be used through either a command line Python interface or as a Sphinx extension, see below for details on both approaches. To install xml2vhdl see the Installation section.

Sphinx Extension

Add the following extensions to your sphinx config (usually conf.py)

extensions = [
    'sphinxcontrib.packetdiag',
    'xml2vhdl',
]

To use make sure you have the following requirements:

• xml2vhdl

• sphinxcontrib-nwdiag

• setuptools==81.0.0

setuptools needs to be pinned at 81.0.0 to ensure sphinxcontrib-nwdiag work, due to it no longer being maintained.

You can also add the following attributes to your sphinx config:

Attribute	Type	Default	Description
xml_file_paths	str or List[str]	None (input is required)	String of list to final xml output file/files, is required
xml_collapse_level	int	3	int for max number of levels of nested node pages
xml_absolute_address	Bool	True	if true all address are absolute, if false all address are relative

CLI Interface

You can also run xml2docs by running with the following command:

usage: xml2docs [-h] -x XML_FILE_PATHS -o OUTPUT_PATH [-c COLLAPSE_LEVEL] [-r]

Named Arguments

-x, --xml_file_paths

String of list to final xml output file/files

-o, --output_path

Path to source of docs folder, where all rst are going to be generated

-c, --collapse_level

int for max number of levels of nested node pages

Default: 3

-r, --relative_address

all address are relative, rather than absolute

Default: False

Using Built Restructured Text Documentation

Xml2Docs creates rst files in a generated/xml2docs folder. You need to include the top level node rst file in a toctree.

.. toctree::

   generated/xml2docs/<top level node id>

You can also import individual register table for a node by using:

.. include:: /generated/xml2docs/<node absolute id>_reg_table.rst.inc