##########
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 :doc:`/usage/installation` section.

Sphinx Extension
================

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

.. code:: python

    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:

.. list-table::
   :header-rows: 1

   * - 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:

.. argparse::
   :module: xml2vhdl.xml2docs
   :func: get_xml2docs_parser
   :prog: xml2docs

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.

.. code-block:: rst

    .. toctree::

       generated/xml2docs/<top level node id>

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

.. code-block:: rst

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