ansys / ansys/pyconverter-xml2py

Handling cross references for paragraphs

Open
#426 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.