docs: documenting latest changes

doc/source/conf.py

@@ -66,6 +66,7 @@
     "jupyter_sphinx",
     "numpydoc",
     "sphinx_autodoc_typehints",
+    "sphinx_click",
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx.ext.autodoc",

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

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
+

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"]

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.

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
+    objects
+    configurations
+    customized_functions

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.

doc/styles/config/vocabularies/ANSYS/accept.txt

@@ -4,6 +4,7 @@ ansys
 API
 autogenerated
 Autogenerated
+custom_functions
 Docbook
 docstring
 isort

pyproject.toml

@@ -70,6 +70,7 @@ doc = [
     "regex==2025.7.34",
     "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",