From 9ccbcf813aef990418c33c4f42093fcec934808c Mon Sep 17 00:00:00 2001
From: clatapie <78221213+clatapie@users.noreply.github.com>
Date: Mon, 11 Aug 2025 12:06:22 +0200
Subject: [PATCH 1/4] docs: documenting latest changes

---
 doc/source/conf.py                            |   1 +
 doc/source/getting_started/index.rst          |  16 ++
 doc/source/user_guide/cli.rst                 | 102 ++++++++++
 doc/source/user_guide/configurations.rst      | 189 ++++++++++++++++++
 .../user_guide/customized_functions.rst       |  13 ++
 doc/source/user_guide/index.rst               |   9 +-
 doc/source/user_guide/objects.rst             |   4 +-
 pyproject.toml                                |   1 +
 src/pyconverter/xml2py/__init__.py            |   4 +-
 src/pyconverter/xml2py/ast_tree.py            |   8 +
 src/pyconverter/xml2py/cli.py                 |   5 +-
 src/pyconverter/xml2py/utils/__init__.py      |   4 +
 12 files changed, 346 insertions(+), 10 deletions(-)
 create mode 100644 doc/source/user_guide/cli.rst
 create mode 100644 doc/source/user_guide/configurations.rst
 create mode 100644 doc/source/user_guide/customized_functions.rst

diff --git a/doc/source/conf.py b/doc/source/conf.py
index b146348cf..30a5277f4 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -66,6 +66,7 @@
     "jupyter_sphinx",
     "numpydoc",
     "sphinx_autodoc_typehints",
+    "sphinx_click",
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx.ext.autodoc",
diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst
index 2dffe5380..befe6c83e 100644
--- a/doc/source/getting_started/index.rst
+++ b/doc/source/getting_started/index.rst
@@ -1,6 +1,8 @@
 Getting started
 ===============
 
+.. _installation:
+
 Installation
 ------------
 
@@ -22,6 +24,20 @@ For developers
 Installing the ``pyconverter-xml2py`` package in developer mode allows you to modify the source and enhance it.
 For contribution guidelines, see :ref:`Contribute <ref_contributing>`.
 
+Quick Start
+-----------
+
+Once installed, you can use PyConverter-XML2Py via the command line interface:
+
+.. code:: bash
+
+    # Check version
+    pyconverter-xml2py version
+
+    # Convert XML documentation to Python package
+    pyconverter-xml2py package -x /path/to/xml/docs
+
+For detailed CLI documentation, see the :doc:`../user_guide/cli` section.
 
 Post issues
 -----------
diff --git a/doc/source/user_guide/cli.rst b/doc/source/user_guide/cli.rst
new file mode 100644
index 000000000..13149abc6
--- /dev/null
+++ b/doc/source/user_guide/cli.rst
@@ -0,0 +1,102 @@
+Command Line Interface
+======================
+
+PyConverter-XML2Py provides a command-line interface (CLI) for converting XML documentation
+into Python packages with Sphinx documentation.
+
+After installing PyConverter-XML2Py, the CLI is available as the ``pyconverter-xml2py`` command.
+Documentation to install the package can be found in the :ref:`installation` section.
+
+
+Quick Start
+-----------
+
+The most basic usage requires only the path to your XML documentation:
+
+.. code:: bash
+
+    pyconverter-xml2py package -x /path/to/xml/docs
+
+This will create a Python package in the current directory with the default template and settings.
+
+Available Commands
+------------------
+
+.. click:: pyconverter.xml2py.cli:main
+   :prog: pyconverter-xml2py
+   :nested: full
+
+
+Environment Variables
+---------------------
+
+.. envvar:: XML_PATH
+
+    Default path for XML documentation directory. If set, you don't need to
+    provide the ``-x`` option.
+
+    .. code:: bash
+
+        export XML_PATH=/path/to/xml/docs
+        pyconverter-xml2py package -p /path/to/output
+
+Usage Examples
+--------------
+
+**Minimal example:**
+
+Convert XML docs to Python package in current directory:
+
+.. code:: bash
+
+    pyconverter-xml2py package \
+        --xml-path ./xml_documentation \
+
+
+**Complete example:**
+
+Convert with all options:
+
+.. code:: bash
+
+    pyconverter-xml2py package \
+        --xml-path ./xml_documentation \
+        --targ-path ./my_package_output \
+        --template-path ./my_template \
+        --func-path ./my_custom_functions \
+        --run-pre-commit \
+        --max-length 150
+
+**Using environment variables:**
+
+.. code:: bash
+
+    export XML_PATH=./xml_documentation
+    pyconverter-xml2py package --targ-path ./output --run-pre-commit
+
+**Check version:**
+
+.. code:: bash
+
+    pyconverter-xml2py version
+
+Troubleshooting
+---------------
+
+**Common Issues:**
+
+1. **"Missing the XML documentation path"**: Make sure to provide either ``-x`` option or set the ``XML_PATH`` environment variable.
+
+2. **"Please, enter a valid directory path"**: Ensure the XML path exists and contains the proper directory structure.
+
+3. **File encoding errors**: On Windows, make sure your XML files are properly encoded (UTF-8 is recommended).
+
+**Getting Help:**
+
+Use the ``--help`` flag to get detailed help for any command:
+
+.. code:: bash
+
+    pyconverter-xml2py --help
+    pyconverter-xml2py package --help
+
diff --git a/doc/source/user_guide/configurations.rst b/doc/source/user_guide/configurations.rst
new file mode 100644
index 000000000..ad49ab945
--- /dev/null
+++ b/doc/source/user_guide/configurations.rst
@@ -0,0 +1,189 @@
+Configuration Files
+===================
+
+PyConverter-XML2Py uses configuration files to customize the conversion process.
+The main configuration is stored in ``config.yaml``.
+
+config.yaml Structure
+---------------------
+
+The ``config.yaml`` file controls various aspects of the package generation process:
+
+.. code:: yaml
+
+    # Package metadata
+    new_package_name: "package"
+    project_name: "MyProject"
+    
+    # Directory structure
+    library_name_structured: ["src", "myproject"]
+    subfolders: ["subfolder1", "subfolder2"]
+    image_folder_path: "images"
+
+    # Command processing
+    rules:
+      "/": slash
+      "*": star
+
+    ignored_commands:
+        - "COMMAND1"
+        - "COMMAND2"
+    
+    specific_command_mapping:
+        "OLD_NAME": "new_name"
+    
+    specific_classes:
+        "OldClassName": "NewClassName"
+    
+    # Custom comments for commands
+    comments:
+        - msg: "Custom comment text"
+          type: "warning"
+          command: ["COMMAND3", "COMMAND4"]
+        - msg: "Another comment"
+          type: "note"
+          command: ["COMMAND5"]
+       
+
+Configuration Options
+---------------------
+
+Package Metadata
+^^^^^^^^^^^^^^^^^
+
+.. option:: new_package_name
+
+    The name of the generated package directory.
+    
+    **Default:** ``"package"``
+
+.. option:: project_name
+
+    The display name of the project used in documentation.
+
+Directory Structure
+^^^^^^^^^^^^^^^^^^^
+
+.. option:: library_name
+
+    List defining the nested directory structure for the generated Python modules.
+    
+    **Example:** ``["src", "myproject"]`` creates ``src/myproject/`` structure
+
+.. option:: subfolders
+
+    List of subfolders where to place the converted files within the package.
+    
+    **Example:** ``["subfolder1", "subfolder2"]`` creates additional directories under the package.
+
+.. option:: image_folder_path
+
+    Relative path where images from the XML documentation will be added.
+    
+    **Default:** ``"images"``
+
+Command Processing
+^^^^^^^^^^^^^^^^^^
+
+.. option:: rules
+
+    Dictionary defining how to handle specific commands or patterns during conversion.
+    
+    **Example:** ``{"/": "slash", "*": "star"}`` maps commands starting with `/` to `slash` and `*` to `star`.
+
+.. option:: ignored_commands
+
+    List of command names to skip during conversion.
+    
+    **Type:** List of strings
+
+.. option:: specific_command_mapping
+
+    Dictionary mapping original command names to custom Python function names.
+    
+    **Example:** ``{"/CLEAR": "clear_all", "*GET": "get_parameter"}``
+
+.. option:: specific_classes
+
+    Dictionary mapping original class names to custom class names.
+    
+    **Example:** ``{"Mesh Controls": "Meshing Controls", "Solver Settings": "Solution Settings"}``
+
+Custom comments
+^^^^^^^^^^^^^^^
+
+.. option:: comments
+
+    Custom comments for specific commands.
+
+    **Type:** List of dictionaries with keys `msg`, `type`, and `command`.
+
+
+Template Configuration
+----------------------
+
+When using custom templates, you can override the default template structure
+by providing a ``template_path`` to the CLI or by placing a custom template
+in the ``_package`` directory.
+
+The template directory should contain:
+
+.. code:: text
+
+    _package/
+    ├── pyproject.toml
+    ├── README.rst
+    ├── LICENSE
+    ├── AUTHORS.md
+    ├── pre-commit-config.yaml
+    └── doc/
+        ├── Makefile
+        ├── make.bat
+        ├── .vale.ini
+        ├── source/
+        │   ├── conf.py
+        │   ├── index.rst
+        │   └── _templates/          # if needed
+        └── styles/
+            └── .gitignore
+            └── Vocab/
+
+Custom Function Configuration
+-----------------------------
+
+For information about configuring custom functions, see :doc:`customized_functions`.
+
+Example Configuration
+---------------------
+
+Here's a complete example ``config.yaml``:
+
+.. code:: yaml
+
+    new_package_name: "my_generated_package"
+    project_name: "My ANSYS Package"
+    
+    library_name_structured: ["src", "ansys", "mypackage"]
+    subfolders: ["utilities", "data_processing"]
+    image_folder_path: "../images"
+    
+    rules:
+      "/": "slash"
+      "*": "star"
+
+    ignored_commands:
+        - "OBSOLETE_CMD"
+        - "DEPRECATED_FUNC"
+    
+    specific_command_mapping:
+        "/CLEAR": "clear_all"
+        "*GET": "get_parameter"
+    
+    specific_classes:
+        "MeshControls": "MeshingControls"
+        "SolverSettings": "SolutionSettings"
+    
+    comments:
+        - msg: "This command is deprecated, use 'new_command' instead."
+          type: "warning"
+          command: ["OLD_COMMAND"]
diff --git a/doc/source/user_guide/customized_functions.rst b/doc/source/user_guide/customized_functions.rst
new file mode 100644
index 000000000..ea8d8cb02
--- /dev/null
+++ b/doc/source/user_guide/customized_functions.rst
@@ -0,0 +1,13 @@
+Customized functions
+====================
+
+If generated functions need to be customized, the following steps can be followed:
+
+1. Identify the function to be customized.
+2. Create a separated file for the customized function, typically in a `function_name.py` file.
+   You can add specific logic in its code, import necessary modules, or create an example section
+   in its docstring for instance.
+3. Repeat the process for any additional functions that need customization.
+4. Add all those function files in a specific folder, such as `custom_functions/`.
+5. Pass the path to this folder in the `custom_functions` argument when running the code generation
+   command.
diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst
index 961e2b37f..0aff16111 100644
--- a/doc/source/user_guide/index.rst
+++ b/doc/source/user_guide/index.rst
@@ -63,11 +63,12 @@ directory by default. This diagram presents the format of the
 
 
 
-
-
-
 .. toctree::
     :maxdepth: 1
+    :hidden:
 
+    cli
     source_code
-    objects
\ No newline at end of file
+    objects
+    configurations
+    customized_functions
\ No newline at end of file
diff --git a/doc/source/user_guide/objects.rst b/doc/source/user_guide/objects.rst
index f9d189baf..6fa5bbcc1 100644
--- a/doc/source/user_guide/objects.rst
+++ b/doc/source/user_guide/objects.rst
@@ -24,7 +24,7 @@ command:
 Tables
 ------
 
-Tables are rendered correctly in the documentation. They do not need to have
+Tables render correctly in the documentation. They do not need to have
 a specific format because the converter uses `flat-tables <flat_tables_>`_.
 
 .. figure:: ./images/tables_doc.png
@@ -37,4 +37,4 @@ a specific format because the converter uses `flat-tables <flat_tables_>`_.
 Links
 -----
 
-Internal and external links are both rendered correctly.
+Internal and external links both render correctly.
diff --git a/pyproject.toml b/pyproject.toml
index f665adcdb..774fecf9d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -70,6 +70,7 @@ doc = [
     "regex==2024.11.6",
     "sphinx-autobuild==2024.10.3",
     "sphinx-autodoc-typehints==3.2.0",
+    "sphinx-click==6.0.0",
     "sphinx-copybutton==0.5.2",
     "sphinx-notfound-page==1.0.4",
     "sphinx-gallery==0.19.0",
diff --git a/src/pyconverter/xml2py/__init__.py b/src/pyconverter/xml2py/__init__.py
index 09c6ec3b8..1319f128d 100644
--- a/src/pyconverter/xml2py/__init__.py
+++ b/src/pyconverter/xml2py/__init__.py
@@ -21,7 +21,7 @@
 # SOFTWARE.
 
 """
-pyconverter.xml2py
+PyConverter-XML2Py
 """
 
 try:
@@ -30,4 +30,4 @@
     import importlib_metadata
 
 __version__ = importlib_metadata.version(__name__.replace(".", "-"))
-"""pyconverter.xml2py version."""
+"""PyConverter-XML2Py version."""
diff --git a/src/pyconverter/xml2py/ast_tree.py b/src/pyconverter/xml2py/ast_tree.py
index 8e39ee7dc..260e35d4a 100644
--- a/src/pyconverter/xml2py/ast_tree.py
+++ b/src/pyconverter/xml2py/ast_tree.py
@@ -128,6 +128,10 @@
 
 
 class NameMap:
+    """
+    Map XML command names to Python function names.
+    """
+
     def __init__(self, name_map):
         self.name_map = name_map
         global NAME_MAP_GLOB
@@ -1626,6 +1630,10 @@ class Code(Element):
 
 
 class _Math(Element):
+    """
+    Provides the math element.
+    """
+
     def __init__(self, element):
         self._element = element
         self._content = []
diff --git a/src/pyconverter/xml2py/cli.py b/src/pyconverter/xml2py/cli.py
index 40816ccb1..c18661f33 100644
--- a/src/pyconverter/xml2py/cli.py
+++ b/src/pyconverter/xml2py/cli.py
@@ -128,7 +128,7 @@ def main():
 @main.command()
 def version():
     """Display current version."""
-    print(f"pyconverter.xml2py {__version__}")
+    print(f"PyConverter-XML2Py {__version__}")
 
 
 @main.command()
@@ -142,7 +142,8 @@ def version():
     "-p",
     "--targ-path",
     type=click.Path(),
-    help="Path where to store the autogenerated package.",
+    default=None,
+    help="Path where to store the autogenerated package. Default value is the current working directory under ``package``.",  # noqa: E501
 )
 @click.option(
     "-t",
diff --git a/src/pyconverter/xml2py/utils/__init__.py b/src/pyconverter/xml2py/utils/__init__.py
index 28e752b2e..f1521193c 100644
--- a/src/pyconverter/xml2py/utils/__init__.py
+++ b/src/pyconverter/xml2py/utils/__init__.py
@@ -20,4 +20,8 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+"""
+Submodule containing usefull methods.
+"""
+
 from . import regex_pattern, utils

From c48675f619f7608151f6999cfbbed0a120f33cdb Mon Sep 17 00:00:00 2001
From: clatapie <78221213+clatapie@users.noreply.github.com>
Date: Thu, 14 Aug 2025 17:27:33 +0200
Subject: [PATCH 2/4] fix: vale

---
 doc/styles/config/vocabularies/ANSYS/accept.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt
index 271e5c669..272ae7a9e 100644
--- a/doc/styles/config/vocabularies/ANSYS/accept.txt
+++ b/doc/styles/config/vocabularies/ANSYS/accept.txt
@@ -4,6 +4,7 @@ ansys
 API
 autogenerated
 Autogenerated
+custom_functions
 Docbook
 docstring
 isort

From 65c01abffcefd4910a09e2c721b13afca36ebb2a Mon Sep 17 00:00:00 2001
From: clatapie <78221213+clatapie@users.noreply.github.com>
Date: Fri, 10 Oct 2025 17:28:43 +0200
Subject: [PATCH 3/4] fix: ``_nolinebreak  ?``

---
 src/pyconverter/xml2py/ast_tree.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/pyconverter/xml2py/ast_tree.py b/src/pyconverter/xml2py/ast_tree.py
index 260e35d4a..a7c30c014 100644
--- a/src/pyconverter/xml2py/ast_tree.py
+++ b/src/pyconverter/xml2py/ast_tree.py
@@ -55,6 +55,7 @@
     '``"``': "``",
     "/_nolinebreak?": "",
     "_nolinebreak?": "",
+    "_nolinebreak ?"
     "nbsp": " ",
 }
 

From e1aaa1f14671cc8f52ea95248130c0a64b93ab05 Mon Sep 17 00:00:00 2001
From: clatapie <78221213+clatapie@users.noreply.github.com>
Date: Mon, 13 Oct 2025 12:29:58 +0200
Subject: [PATCH 4/4] revert: last change

---
 src/pyconverter/xml2py/ast_tree.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/pyconverter/xml2py/ast_tree.py b/src/pyconverter/xml2py/ast_tree.py
index a7c30c014..260e35d4a 100644
--- a/src/pyconverter/xml2py/ast_tree.py
+++ b/src/pyconverter/xml2py/ast_tree.py
@@ -55,7 +55,6 @@
     '``"``': "``",
     "/_nolinebreak?": "",
     "_nolinebreak?": "",
-    "_nolinebreak ?"
     "nbsp": " ",
 }