User guide
==========

This section provides some guidelines for using PyConverter-XML2Py.
You can modify each step as needed to convert your own Docbook XML documentation.


Predefined format
-----------------

The conversion is based on a predefined XML directory format that you
should follow:

.. include:: ./images/diags/diag_directory.rst


Template directory
------------------

The ``_package`` directory is the template that the autogenerated package
follows.


Convert an XML directory
------------------------

Once the ``XML_directory`` is correctly organized, you can use this command
to run the converter:

.. code:: bash

    pyconverter-xml2py package -x XML_directory_path


If you need to customize some functions, you can specify the path containing the
Python files:

.. code:: bash

    pyconverter-xml2py package -x XML_directory_path -f customized_function_directory_path


For more information, see :ref:`ref_source_code`.

After the converter runs, you can generate Sphinx documentation. This code renders
the documentation as HTML from Windows:

.. code:: bash

    cd package
    pip install -e .[doc] # The use of a virtual environment is recommended.
    .\doc\make.bat html 


Autogenerated package
---------------------
The Sphinx documentation is contained in the autogenerated ``package``
directory by default. This diagram presents the format of the
``package`` directory:  

.. include:: ./images/diags/diag_package.rst







.. toctree::
    :maxdepth: 1

    source_code
    objects