ansible-community / ansible-community/antsibull-docs-parser
Issues with defining links when using the to_rst and to_md filters
- Dominant language
- Python
- Stars
- 8
- Forks
- 4
- Avg merge
- 3h 2m
- Merged PRs (30d)
- 2
Description
I am the author of the [ansible-doc-template-extractor](https://pypi.org/project/ansible-doc-template-extractor/) package which uses the `to_rst` and `to_md` Jinja2 filters of this repo.
These filters do such a thorough job in [escaping](https://github.com/ansible-community/antsibull-docs-parser/blob/main/src/antsibull_docs_parser/rst.py#L24) that it is basically impossible to create a link in the filter input text that survives as a link.
Examples for input text and output text for the `to_rst` filter:
```
Input to_rst output
------------------------------------------------------------------------------------------------------
:ref:`my_ref_target` :ref:\`my\_ref\_target\`
`my ref target <../myfile.html#my-ref-target>`_ \`my ref target \<../myfile.html#my-ref-target\>\`\_
|my_ref_target| \|my\_ref\_target\|
```
Can we please have some support for defining links using RST syntax using `:ref:` and MD link syntax `[]()`?
I can think of the following options:
* Option 1: Always allow these links in [postprocess_rst_paragraph()](https://github.com/ansible-community/antsibull-docs-parser/blob/main/src/antsibull_docs_parser/rst.py#L361) and [postprocess_md_paragraph()](https://github.com/ansible-community/antsibull-docs-parser/blob/main/src/antsibull_docs_parser/md.py#L104)
* Option 2: Add an optional parameter on the `to_rst` and `to_md` filters that specifies a string with the characters that should not be escaped.
* Option 3: Add an optional parameter on the `to_rst` and `to_md` filters that specifies a custom `postprocess_paragraph()` function, replacing the default one (or in addition to the default one).
* Option 4: Some Ansible-style way of linking to RST targets or MD headings.
What do you think about this?
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading postprocess_rst_paragraph() in antsibull_docs_parser/rst.py and postprocess_md_paragraph() in antsibull_docs_parser/md.py, then trace how the to_rst and to_md filters invoke them. Compare the proposed RST and Markdown link forms and determine a clear supported behavior; done means links survive filtering without breaking the existing escaping behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 38/100