ansys / ansys/pyconverter-xml2py
Handling paragraphs in ``Parameters`` section
- Dominant language
- Python
- Stars
- 6
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
### Description of the modifications
According to Sphinx references, ``Parameters`` section should look as follow:
```py
Parameters
----------
arg1: str
text
arg 2: str
text
arg3: str
text
arg4: str
text
```
However, the MAPDL documentation sometimes is written with the following format:
```py
arg1: text
if arg1=special_value: # paragraph section not displayed
arg2: text # argument section at the same level as arg1
arg3: text
arg4: text
```
The paragraph section in the middle of the argument description can not be added to follow Sphinx formatting. To avoid a high number of missing description, this format is "accepted" and descriptions of the arguments are added to the argument descriptions. As the paragraph section cannot be displayed, a warning at the beginning of the **Notes** section is added.
However, the following format is not accepted by the converter and a missing description mention is added to the argument definition:
```py
arg1: text
if arg1=special_value: # paragraph section not displayed
arg2: text # argument description nested into the paragraph
arg3: text
arg4: text
```
This is due to argument definitions nested into paragraphs.
This is the case for ``units`` function - see https://github.com/ansys/pymapdl/pull/3748/files#r2037800169 discussion.
This requires additional changes in the way paragraphs are handled.
An enhancement could also be done for adding the ``if arg1=special_value`` mention in the notes section.
Tasks to be done:
- [ ] handle the arguments nested into a paragraph section
- [ ] add the paragraph sections in the ``Notes`` section
- [ ] add documentation about these specificities in pyconverter-xml2py documentation
### Useful links and references
_No response_
Contributor guide
Research direction
Start with the paragraph-handling path in the converter and inspect the units function case described in the linked pull request discussion. Trace how nested argument definitions are currently reported, then review the pyconverter-xml2py documentation requirements. Done means nested arguments are handled, paragraph sections are represented in Notes, and the converter documentation explains these formats.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100