ansible-community / ansible-community/antsibull-docs-parser

Issues with defining links when using the to_rst and to_md filters

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.