ansys / ansys/pyconverter-xml2py
Handling cross references for paragraphs
- Dominant language
- Python
- Stars
- 6
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
MAPDL documentation contains a lot of links referring to paragraph sections with no title.
However, Sphinx only accepts labels before a heading or a rubric.
Thus, calling the following ``NSORTinputneed`` reference doesn't render correctly:
```
.. _NSORTinputneed:
Works only if failure criteria information is provided. (For more information, see the documentation
for the :ref:`fc` and :ref:`tb` commands.)
```
Addressing the issue
----------------------
An easy way to fix it would be by adding a default title to each paragraph section with a ``rubric`` link object, for instance:
```
.. _NSORTinputneed:
.. rubric:: NSORTinputneed
Works only if failure criteria information is provided. (For more information, see the documentation
for the :ref:`fc` and :ref:`tb` commands.)
```
Links
-----
- ``nsort``: https://github.com/ansys/pymapdl/pull/4003#discussion_r2142302046
- ``pdef``: https://github.com/ansys/pymapdl/pull/4003#discussion_r2142266523
Contributor guide
Research direction
Start by inspecting the generated MAPDL documentation around the nsort and pdef sections, then review the linked pull-request discussions for the existing cross-reference examples. Check how paragraph anchors such as NSORTinputneed are represented and verify that their links render correctly with the related fc and tb references.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100