Skip to content

Commit dc29608

Browse files
felixfonteinfelixfontein
authored
Fix label casing (#172)
* Fix reference casing. * Factor out utility function. * Add tests.
1 parent e3122b3 commit dc29608

File tree

13 files changed

+113
-6
lines changed

13 files changed

+113
-6
lines changed

‎changelogs/fragments/172-ref-casing.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
bugfixes:
2+
- "Make sure that ``:ansopt:`` and ``:ansretval:`` create the same references as the labels created in the RST files (https://github.com/ansible-community/antsibull-docs/issues/167, https://github.com/ansible-community/antsibull-docs/pull/172)."

‎src/antsibull_docs/augment_docs.py

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
import typing as t
1111
from collections.abc import Mapping, MutableMapping
1212

13+
from antsibull_docs.utils.rst import massage_rst_label
14+
1315

1416
def add_full_key(
1517
options_data: Mapping[str, t.Any],
@@ -53,7 +55,7 @@ def add_full_key(
5355
entry["full_key"] = full_key_k
5456
entry["full_keys"] = full_keys_k
5557
entry["full_keys_rst"] = sorted(
56-
{tuple(" ".join(p.lower().split()) for p in fk) for fk in full_keys_k}
58+
{tuple(massage_rst_label(p) for p in fk) for fk in full_keys_k}
5759
)
5860

5961
# Process suboptions

‎src/antsibull_docs/utils/rst.py

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
2+
# https://www.gnu.org/licenses/gpl-3.0.txt)
3+
# SPDX-License-Identifier: GPL-3.0-or-later
4+
# SPDX-FileCopyrightText: 2022, Ansible Project
5+
"""
6+
ReStructured Text utils.
7+
"""
8+
9+
10+
def massage_rst_label(label: str) -> str:
11+
return " ".join(label.lower().split())

‎src/sphinx_antsibull_ext/roles.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
from sphinx import addnodes
1616

1717
from antsibull_docs.markup.semantic_helper import parse_option, parse_return_value
18+
from antsibull_docs.utils.rst import massage_rst_label
1819

1920

2021
# pylint:disable-next=unused-argument,dangerous-default-value
@@ -101,7 +102,7 @@ def _create_option_reference(
101102
) -> str | None:
102103
if not plugin_fqcn or not plugin_type:
103104
return None
104-
ref = option.replace(".", "/")
105+
ref = massage_rst_label(option.replace(".", "/"))
105106
ep = f"{entrypoint}__" if entrypoint is not None else ""
106107
return f"ansible_collections.{plugin_fqcn}_{plugin_type}__parameter-{ep}{ref}"
107108

@@ -114,7 +115,7 @@ def _create_return_value_reference(
114115
) -> str | None:
115116
if not plugin_fqcn or not plugin_type:
116117
return None
117-
ref = return_value.replace(".", "/")
118+
ref = massage_rst_label(return_value.replace(".", "/"))
118119
ep = f"{entrypoint}__" if entrypoint is not None else ""
119120
return f"ansible_collections.{plugin_fqcn}_{plugin_type}__return-{ep}{ref}"
120121

‎tests/functional/ansible-doc-cache-all-others.json

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22704,6 +22704,10 @@
2270422704
"subfoo": {
2270522705
"description": "Some recursive foo.",
2270622706
"suboptions": {
22707+
"BaZ": {
22708+
"description": "Funky.",
22709+
"type": "int"
22710+
},
2270722711
"foo": {
2270822712
"description": [
2270922713
"A sub foo.",
@@ -22868,7 +22872,8 @@
2286822872
"M(ext.col.foo)",
2286922873
"P(ext.col.bar#lookup)",
2287022874
"O(ext.col.foo#module:foo[len(foo\\)].bar)",
22871-
"RV(ext.col.foo#module:baz[])"
22875+
"RV(ext.col.foo#module:baz[])",
22876+
"O(ns.col2.foo2#module:subfoo.BaZ)"
2287222877
]
2287322878
},
2287422879
"not_existing": {

‎tests/functional/ansible-doc-cache-all.json

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22623,6 +22623,10 @@
2262322623
"subfoo": {
2262422624
"description": "Some recursive foo.",
2262522625
"suboptions": {
22626+
"BaZ": {
22627+
"description": "Funky.",
22628+
"type": "int"
22629+
},
2262622630
"foo": {
2262722631
"description": [
2262822632
"A sub foo.",
@@ -22787,7 +22791,8 @@
2278722791
"M(ext.col.foo)",
2278822792
"P(ext.col.bar#lookup)",
2278922793
"O(ext.col.foo#module:foo[len(foo\\)].bar)",
22790-
"RV(ext.col.foo#module:baz[])"
22794+
"RV(ext.col.foo#module:baz[])",
22795+
"O(ns.col2.foo2#module:subfoo.BaZ)"
2279122796
]
2279222797
},
2279322798
"not_existing": {

‎tests/functional/ansible-doc-cache-ns.col2.json

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -784,6 +784,10 @@
784784
"subfoo": {
785785
"description": "Some recursive foo.",
786786
"suboptions": {
787+
"BaZ": {
788+
"description": "Funky.",
789+
"type": "int"
790+
},
787791
"foo": {
788792
"description": [
789793
"A sub foo.",
@@ -948,7 +952,8 @@
948952
"M(ext.col.foo)",
949953
"P(ext.col.bar#lookup)",
950954
"O(ext.col.foo#module:foo[len(foo\\)].bar)",
951-
"RV(ext.col.foo#module:baz[])"
955+
"RV(ext.col.foo#module:baz[])",
956+
"O(ns.col2.foo2#module:subfoo.BaZ)"
952957
]
953958
},
954959
"not_existing": {

‎tests/functional/baseline-default/collections/ns/col2/foo2_module.rst

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -210,6 +210,40 @@ Parameters
210210

211211
</div>
212212

213+
* - .. raw:: html
214+
215+
<div class="ansible-option-indent"></div><div class="ansible-option-cell">
216+
<div class="ansibleOptionAnchor" id="parameter-subfoo/BaZ"></div>
217+
218+
.. _ansible_collections.ns.col2.foo2_module__parameter-subfoo/baz:
219+
220+
.. rst-class:: ansible-option-title
221+
222+
**BaZ**
223+
224+
.. raw:: html
225+
226+
<a class="ansibleOptionLink" href="#parameter-subfoo/BaZ" title="Permalink to this option"></a>
227+
228+
.. rst-class:: ansible-option-type-line
229+
230+
:ansible-option-type:`integer`
231+
232+
.. raw:: html
233+
234+
</div>
235+
236+
- .. raw:: html
237+
238+
<div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">
239+
240+
Funky.
241+
242+
243+
.. raw:: html
244+
245+
</div>
246+
213247
* - .. raw:: html
214248

215249
<div class="ansible-option-indent"></div><div class="ansible-option-cell">

‎tests/functional/baseline-default/collections/ns/col2/foo4_module.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,8 @@ Parameters
157157

158158
\ :ansretval:`ext.col.foo#module:baz[]`\
159159

160+
\ :ansopt:`ns.col2.foo2#module:subfoo.BaZ`\
161+
160162

161163
.. raw:: html
162164

‎tests/functional/baseline-no-breadcrumbs/collections/ns/col2/foo2_module.rst

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -210,6 +210,40 @@ Parameters
210210

211211
</div>
212212

213+
* - .. raw:: html
214+
215+
<div class="ansible-option-indent"></div><div class="ansible-option-cell">
216+
<div class="ansibleOptionAnchor" id="parameter-subfoo/BaZ"></div>
217+
218+
.. _ansible_collections.ns.col2.foo2_module__parameter-subfoo/baz:
219+
220+
.. rst-class:: ansible-option-title
221+
222+
**BaZ**
223+
224+
.. raw:: html
225+
226+
<a class="ansibleOptionLink" href="#parameter-subfoo/BaZ" title="Permalink to this option"></a>
227+
228+
.. rst-class:: ansible-option-type-line
229+
230+
:ansible-option-type:`integer`
231+
232+
.. raw:: html
233+
234+
</div>
235+
236+
- .. raw:: html
237+
238+
<div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">
239+
240+
Funky.
241+
242+
243+
.. raw:: html
244+
245+
</div>
246+
213247
* - .. raw:: html
214248

215249
<div class="ansible-option-indent"></div><div class="ansible-option-cell">

0 commit comments

Comments
 (0)