Skip to content

Commit 9ccbcf8

Browse files
clatapieclatapie
committed
docs: documenting latest changes
1 parent 5bf846e commit 9ccbcf8

File tree

12 files changed

+346
-10
lines changed

12 files changed

+346
-10
lines changed

‎doc/source/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@
6666
"jupyter_sphinx",
6767
"numpydoc",
6868
"sphinx_autodoc_typehints",
69+
"sphinx_click",
6970
"sphinx_copybutton",
7071
"sphinx_design",
7172
"sphinx.ext.autodoc",

‎doc/source/getting_started/index.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
Getting started
22
===============
33

4+
.. _installation:
5+
46
Installation
57
------------
68

@@ -22,6 +24,20 @@ For developers
2224
Installing the ``pyconverter-xml2py`` package in developer mode allows you to modify the source and enhance it.
2325
For contribution guidelines, see :ref:`Contribute <ref_contributing>`.
2426

27+
Quick Start
28+
-----------
29+
30+
Once installed, you can use PyConverter-XML2Py via the command line interface:
31+
32+
.. code:: bash
33+
34+
# Check version
35+
pyconverter-xml2py version
36+
37+
# Convert XML documentation to Python package
38+
pyconverter-xml2py package -x /path/to/xml/docs
39+
40+
For detailed CLI documentation, see the :doc:`../user_guide/cli` section.
2541

2642
Post issues
2743
-----------

‎doc/source/user_guide/cli.rst‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
Command Line Interface
2+
======================
3+
4+
PyConverter-XML2Py provides a command-line interface (CLI) for converting XML documentation
5+
into Python packages with Sphinx documentation.
6+
7+
After installing PyConverter-XML2Py, the CLI is available as the ``pyconverter-xml2py`` command.
8+
Documentation to install the package can be found in the :ref:`installation` section.
9+
10+
11+
Quick Start
12+
-----------
13+
14+
The most basic usage requires only the path to your XML documentation:
15+
16+
.. code:: bash
17+
18+
pyconverter-xml2py package -x /path/to/xml/docs
19+
20+
This will create a Python package in the current directory with the default template and settings.
21+
22+
Available Commands
23+
------------------
24+
25+
.. click:: pyconverter.xml2py.cli:main
26+
:prog: pyconverter-xml2py
27+
:nested: full
28+
29+
30+
Environment Variables
31+
---------------------
32+
33+
.. envvar:: XML_PATH
34+
35+
Default path for XML documentation directory. If set, you don't need to
36+
provide the ``-x`` option.
37+
38+
.. code:: bash
39+
40+
export XML_PATH=/path/to/xml/docs
41+
pyconverter-xml2py package -p /path/to/output
42+
43+
Usage Examples
44+
--------------
45+
46+
**Minimal example:**
47+
48+
Convert XML docs to Python package in current directory:
49+
50+
.. code:: bash
51+
52+
pyconverter-xml2py package \
53+
--xml-path ./xml_documentation \
54+
55+
56+
**Complete example:**
57+
58+
Convert with all options:
59+
60+
.. code:: bash
61+
62+
pyconverter-xml2py package \
63+
--xml-path ./xml_documentation \
64+
--targ-path ./my_package_output \
65+
--template-path ./my_template \
66+
--func-path ./my_custom_functions \
67+
--run-pre-commit \
68+
--max-length 150
69+
70+
**Using environment variables:**
71+
72+
.. code:: bash
73+
74+
export XML_PATH=./xml_documentation
75+
pyconverter-xml2py package --targ-path ./output --run-pre-commit
76+
77+
**Check version:**
78+
79+
.. code:: bash
80+
81+
pyconverter-xml2py version
82+
83+
Troubleshooting
84+
---------------
85+
86+
**Common Issues:**
87+
88+
1. **"Missing the XML documentation path"**: Make sure to provide either ``-x`` option or set the ``XML_PATH`` environment variable.
89+
90+
2. **"Please, enter a valid directory path"**: Ensure the XML path exists and contains the proper directory structure.
91+
92+
3. **File encoding errors**: On Windows, make sure your XML files are properly encoded (UTF-8 is recommended).
93+
94+
**Getting Help:**
95+
96+
Use the ``--help`` flag to get detailed help for any command:
97+
98+
.. code:: bash
99+
100+
pyconverter-xml2py --help
101+
pyconverter-xml2py package --help
102+

‎doc/source/user_guide/configurations.rst‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
Configuration Files
2+
===================
3+
4+
PyConverter-XML2Py uses configuration files to customize the conversion process.
5+
The main configuration is stored in ``config.yaml``.
6+
7+
config.yaml Structure
8+
---------------------
9+
10+
The ``config.yaml`` file controls various aspects of the package generation process:
11+
12+
.. code:: yaml
13+
14+
# Package metadata
15+
new_package_name: "package"
16+
project_name: "MyProject"
17+
18+
# Directory structure
19+
library_name_structured: ["src", "myproject"]
20+
subfolders: ["subfolder1", "subfolder2"]
21+
image_folder_path: "images"
22+
23+
# Command processing
24+
rules:
25+
"/": slash
26+
"*": star
27+
28+
ignored_commands:
29+
- "COMMAND1"
30+
- "COMMAND2"
31+
32+
specific_command_mapping:
33+
"OLD_NAME": "new_name"
34+
35+
specific_classes:
36+
"OldClassName": "NewClassName"
37+
38+
# Custom comments for commands
39+
comments:
40+
- msg: "Custom comment text"
41+
type: "warning"
42+
command: ["COMMAND3", "COMMAND4"]
43+
- msg: "Another comment"
44+
type: "note"
45+
command: ["COMMAND5"]
46+
47+
48+
Configuration Options
49+
---------------------
50+
51+
Package Metadata
52+
^^^^^^^^^^^^^^^^^
53+
54+
.. option:: new_package_name
55+
56+
The name of the generated package directory.
57+
58+
**Default:** ``"package"``
59+
60+
.. option:: project_name
61+
62+
The display name of the project used in documentation.
63+
64+
Directory Structure
65+
^^^^^^^^^^^^^^^^^^^
66+
67+
.. option:: library_name
68+
69+
List defining the nested directory structure for the generated Python modules.
70+
71+
**Example:** ``["src", "myproject"]`` creates ``src/myproject/`` structure
72+
73+
.. option:: subfolders
74+
75+
List of subfolders where to place the converted files within the package.
76+
77+
**Example:** ``["subfolder1", "subfolder2"]`` creates additional directories under the package.
78+
79+
.. option:: image_folder_path
80+
81+
Relative path where images from the XML documentation will be added.
82+
83+
**Default:** ``"images"``
84+
85+
Command Processing
86+
^^^^^^^^^^^^^^^^^^
87+
88+
.. option:: rules
89+
90+
Dictionary defining how to handle specific commands or patterns during conversion.
91+
92+
**Example:** ``{"/": "slash", "*": "star"}`` maps commands starting with `/` to `slash` and `*` to `star`.
93+
94+
.. option:: ignored_commands
95+
96+
List of command names to skip during conversion.
97+
98+
**Type:** List of strings
99+
100+
.. option:: specific_command_mapping
101+
102+
Dictionary mapping original command names to custom Python function names.
103+
104+
**Example:** ``{"/CLEAR": "clear_all", "*GET": "get_parameter"}``
105+
106+
.. option:: specific_classes
107+
108+
Dictionary mapping original class names to custom class names.
109+
110+
**Example:** ``{"Mesh Controls": "Meshing Controls", "Solver Settings": "Solution Settings"}``
111+
112+
Custom comments
113+
^^^^^^^^^^^^^^^
114+
115+
.. option:: comments
116+
117+
Custom comments for specific commands.
118+
119+
**Type:** List of dictionaries with keys `msg`, `type`, and `command`.
120+
121+
122+
Template Configuration
123+
----------------------
124+
125+
When using custom templates, you can override the default template structure
126+
by providing a ``template_path`` to the CLI or by placing a custom template
127+
in the ``_package`` directory.
128+
129+
The template directory should contain:
130+
131+
.. code:: text
132+
133+
_package/
134+
├── pyproject.toml
135+
├── README.rst
136+
├── LICENSE
137+
├── AUTHORS.md
138+
├── pre-commit-config.yaml
139+
└── doc/
140+
├── Makefile
141+
├── make.bat
142+
├── .vale.ini
143+
├── source/
144+
│ ├── conf.py
145+
│ ├── index.rst
146+
│ └── _templates/ # if needed
147+
└── styles/
148+
└── .gitignore
149+
└── Vocab/
150+
151+
Custom Function Configuration
152+
-----------------------------
153+
154+
For information about configuring custom functions, see :doc:`customized_functions`.
155+
156+
Example Configuration
157+
---------------------
158+
159+
Here's a complete example ``config.yaml``:
160+
161+
.. code:: yaml
162+
163+
new_package_name: "my_generated_package"
164+
project_name: "My ANSYS Package"
165+
166+
library_name_structured: ["src", "ansys", "mypackage"]
167+
subfolders: ["utilities", "data_processing"]
168+
image_folder_path: "../images"
169+
170+
rules:
171+
"/": "slash"
172+
"*": "star"
173+
174+
ignored_commands:
175+
- "OBSOLETE_CMD"
176+
- "DEPRECATED_FUNC"
177+
178+
specific_command_mapping:
179+
"/CLEAR": "clear_all"
180+
"*GET": "get_parameter"
181+
182+
specific_classes:
183+
"MeshControls": "MeshingControls"
184+
"SolverSettings": "SolutionSettings"
185+
186+
comments:
187+
- msg: "This command is deprecated, use 'new_command' instead."
188+
type: "warning"
189+
command: ["OLD_COMMAND"]

‎doc/source/user_guide/customized_functions.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Customized functions
2+
====================
3+
4+
If generated functions need to be customized, the following steps can be followed:
5+
6+
1. Identify the function to be customized.
7+
2. Create a separated file for the customized function, typically in a `function_name.py` file.
8+
You can add specific logic in its code, import necessary modules, or create an example section
9+
in its docstring for instance.
10+
3. Repeat the process for any additional functions that need customization.
11+
4. Add all those function files in a specific folder, such as `custom_functions/`.
12+
5. Pass the path to this folder in the `custom_functions` argument when running the code generation
13+
command.

‎doc/source/user_guide/index.rst‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -63,11 +63,12 @@ directory by default. This diagram presents the format of the
6363

6464

6565

66-
67-
68-
6966
.. toctree::
7067
:maxdepth: 1
68+
:hidden:
7169

70+
cli
7271
source_code
73-
objects
72+
objects
73+
configurations
74+
customized_functions

‎doc/source/user_guide/objects.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ command:
2424
Tables
2525
------
2626

27-
Tables are rendered correctly in the documentation. They do not need to have
27+
Tables render correctly in the documentation. They do not need to have
2828
a specific format because the converter uses `flat-tables <flat_tables_>`_.
2929

3030
.. figure:: ./images/tables_doc.png
@@ -37,4 +37,4 @@ a specific format because the converter uses `flat-tables <flat_tables_>`_.
3737
Links
3838
-----
3939

40-
Internal and external links are both rendered correctly.
40+
Internal and external links both render correctly.

‎pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ doc = [
7070
"regex==2024.11.6",
7171
"sphinx-autobuild==2024.10.3",
7272
"sphinx-autodoc-typehints==3.2.0",
73+
"sphinx-click==6.0.0",
7374
"sphinx-copybutton==0.5.2",
7475
"sphinx-notfound-page==1.0.4",
7576
"sphinx-gallery==0.19.0",

0 commit comments

Comments
 (0)