Skip to content

Commit c887263

Browse files
felixfonteinfelixfontein
committed
Improve reference titles and parmalink titles.
1 parent 651c202 commit c887263

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+119
-149
lines changed

‎src/antsibull_docs/data/docsite/ansible-docsite/macros/parameters.rst.j2

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
{% from 'macros/deprecates.rst.j2' import in_html as deprecates_html with context %}
1111
{% from 'macros/version_added.rst.j2' import version_added_rst, version_added_html %}
1212

13-
{% macro in_rst(elements, suboption_key='suboptions', role_entrypoint=None) %}
13+
{% macro in_rst(elements, suboption_key='suboptions', role_entrypoint=None, special=None) %}
1414
.. tabularcolumns:: \X{1}{3}\X{2}{3}
1515

1616
.. list-table::
@@ -46,6 +46,9 @@
4646
{% for full_key in value['full_keys'] %}
4747
- @{ full_key | antsibull_to_json }@
4848
{% endfor %}
49+
{% if special is not none %}
50+
special: @{ special }@
51+
{% endif %}
4952

5053
.. ansible-option-type-line::
5154
{% if value['aliases'] %}
@@ -178,7 +181,7 @@
178181

179182
{##################################################################################################################}
180183

181-
{% macro in_html(elements, suboption_key='suboptions', role_entrypoint=None) %}
184+
{% macro in_html(elements, suboption_key='suboptions', role_entrypoint=None, special=None) %}
182185
.. raw:: html
183186

184187
<table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">

‎src/antsibull_docs/data/docsite/ansible-docsite/macros/returnvalues.rst.j2

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
{% from 'macros/choiceslist.rst.j2' import in_html as choices_html %}
99
{% from 'macros/version_added.rst.j2' import version_added_rst, version_added_html %}
1010

11-
{% macro in_rst(elements, role_entrypoint=None) %}
11+
{% macro in_rst(elements, role_entrypoint=None, special=None) %}
1212
.. tabularcolumns:: \X{1}{3}\X{2}{3}
1313

1414
.. list-table::
@@ -44,9 +44,9 @@
4444
{% for full_key in value['full_keys'] %}
4545
- @{ full_key | antsibull_to_json }@
4646
{% endfor %}
47-
48-
.. raw:: html
49-
:url: data:text/plain;base64,IA==
47+
{% if special is not none %}
48+
special: @{ special }@
49+
{% endif %}
5050

5151
.. ansible-option-type-line::
5252

@@ -114,7 +114,7 @@
114114

115115
{##################################################################################################################}
116116

117-
{% macro in_html(elements, role_entrypoint=None) %}
117+
{% macro in_html(elements, role_entrypoint=None, special=None) %}
118118
.. raw:: html
119119

120120
<table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">

‎src/antsibull_docs/data/docsite/ansible-docsite/plugin.rst.j2

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -190,9 +190,9 @@ Terms
190190
-----
191191

192192
{% if use_html_blobs %}
193-
@{ parameters_html([['Terms', doc['options']['_terms']]], suboption_key='suboptions') }@
193+
@{ parameters_html([['Terms', doc['options']['_terms']]], suboption_key='suboptions', special='terms') }@
194194
{% else %}
195-
@{ parameters_rst([['Terms', doc['options']['_terms']]], suboption_key='suboptions') }@
195+
@{ parameters_rst([['Terms', doc['options']['_terms']]], suboption_key='suboptions', special='terms') }@
196196
{% endif %}
197197

198198
{% endif %}
@@ -212,9 +212,9 @@ This describes the input of the test, the value before ``is @{plugin_name}@`` or
212212
{% endif %}
213213

214214
{% if use_html_blobs %}
215-
@{ parameters_html([['Input', doc['options']['_input']]], suboption_key='suboptions') }@
215+
@{ parameters_html([['Input', doc['options']['_input']]], suboption_key='suboptions', special='input') }@
216216
{% else %}
217-
@{ parameters_rst([['Input', doc['options']['_input']]], suboption_key='suboptions') }@
217+
@{ parameters_rst([['Input', doc['options']['_input']]], suboption_key='suboptions', special='input') }@
218218
{% endif %}
219219

220220
{% endif %}
@@ -236,9 +236,9 @@ examples: ``input is @{plugin_name}@(positional1, positional2, ...)`` and ``inpu
236236
{% endif %}
237237

238238
{% if use_html_blobs %}
239-
@{ parameters_html(doc['options'] | extract_options_from_list(doc['positional'], options_to_ignore=['_input']), suboption_key='suboptions') }@
239+
@{ parameters_html(doc['options'] | extract_options_from_list(doc['positional'], options_to_ignore=['_input']), suboption_key='suboptions', special='positional') }@
240240
{% else %}
241-
@{ parameters_rst(doc['options'] | extract_options_from_list(doc['positional'], options_to_ignore=['_input']), suboption_key='suboptions') }@
241+
@{ parameters_rst(doc['options'] | extract_options_from_list(doc['positional'], options_to_ignore=['_input']), suboption_key='suboptions', special='positional') }@
242242
{% endif %}
243243

244244
{% endif %}
@@ -362,9 +362,9 @@ Returned Facts
362362
Facts returned by this module are added/updated in the ``hostvars`` host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.
363363

364364
{% if use_html_blobs %}
365-
@{ return_docs_html(returnfacts | dictsort) }@
365+
@{ return_docs_html(returnfacts | dictsort, special='facts') }@
366366
{% else %}
367-
@{ return_docs_rst(returnfacts | dictsort) }@
367+
@{ return_docs_rst(returnfacts | dictsort, special='facts') }@
368368
{% endif %}
369369
{% endif %}
370370

@@ -383,9 +383,9 @@ Return Value
383383

384384
{% if plugin_type in ['lookup', 'filter', 'test'] and returndocs | length == 1 and (returndocs | first).startswith('_') %}
385385
{% if use_html_blobs %}
386-
@{ return_docs_html([['Return value', returndocs.values() | first]]) }@
386+
@{ return_docs_html([['Return value', returndocs.values() | first]], special='return-value') }@
387387
{% else %}
388-
@{ return_docs_rst([['Return value', returndocs.values() | first]]) }@
388+
@{ return_docs_rst([['Return value', returndocs.values() | first]], special='return-value') }@
389389
{% endif %}
390390
{% else %}
391391
{% if use_html_blobs %}

‎src/sphinx_antsibull_ext/directives.py

Lines changed: 47 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -244,9 +244,8 @@ def _run(
244244
rst_id = (
245245
f"ansible_collections.{content.fqcn}_{content.plugin_type}_requirements"
246246
)
247-
ref_title = (
248-
f"Requirements of the {_plugin_name(content.fqcn, content.plugin_type)}"
249-
)
247+
plugin_name = _plugin_name(content.fqcn, content.plugin_type)
248+
ref_title = f"Requirements of the {plugin_name}"
250249
if content.role_entrypoint is not None and content.plugin_type == "role":
251250
rst_id = (
252251
f"ansible_collections.{content.fqcn}_role"
@@ -278,13 +277,14 @@ def _run(self, content_str: str, content: AnsibleAttribute) -> list[nodes.Node]:
278277
node = ansible_attribute(
279278
"", content.name, classes=["ansible-option-title"], ids=[html_id]
280279
)
280+
plugin_name = _plugin_name(content.fqcn, content.plugin_type)
281281
self.state.document.note_explicit_target(node)
282282
std = t.cast(StandardDomain, self.env.get_domain("std"))
283283
std.note_hyperlink_target(
284284
rst_id,
285285
self.env.docname,
286286
html_id,
287-
f"{content.name} attribute of {_plugin_name(content.fqcn, content.plugin_type)}",
287+
f"{content.name} attribute of {plugin_name}",
288288
)
289289
permalink = nodes.raw(
290290
"",
@@ -309,7 +309,7 @@ def _compile_ids(
309309
role_entrypoint: str | None,
310310
full_keys: list[list[str]],
311311
prefix_type: str,
312-
) -> tuple[dict[str, tuple[str, str]], list[str]]:
312+
) -> tuple[dict[str, tuple[str, str, str]], list[str]]:
313313
rst_id_prefix = f"ansible_collections.{fqcn}_{plugin_type}__{prefix_type}-"
314314
html_id_prefix = f"{prefix_type}-"
315315
if role_entrypoint is not None:
@@ -321,7 +321,7 @@ def _compile_ids(
321321
html_id = html_id_prefix + "/".join([_percent_encode(k) for k in full_key])
322322
rst_id = rst_id_prefix + "/".join([massage_rst_label(k) for k in full_key])
323323
html_ids.append(html_id)
324-
rst_ids[rst_id] = (html_id, ".".join(full_key))
324+
rst_ids[rst_id] = (html_id, ".".join(full_key), ".".join(full_key[1:]))
325325
return rst_ids, _make_unique(html_ids)
326326

327327

@@ -342,19 +342,41 @@ def _run(self, content_str: str, content: AnsibleOption) -> list[nodes.Node]:
342342
classes=["ansible-option-title"],
343343
ids=html_ids,
344344
)
345+
what_title = "{key} option of"
346+
what_perma = "this option"
347+
if content.plugin_type in ("lookup", "filter", "test"):
348+
what_title = "{key} keyword option of"
349+
what_perma = "this keyword option"
350+
if content.special == "positional":
351+
what_title = "{key} positional option of"
352+
what_perma = "this positional option"
353+
if content.special == "input":
354+
what_title = "input of"
355+
what_perma = f"the {content.plugin_type}'s input"
356+
if len(content.full_keys[0]) > 1:
357+
what_title = "nested input field {subkey} of"
358+
what_perma = f"this nested field of the {content.plugin_type}'s input"
359+
if content.special == "terms":
360+
what_title = "terms for the"
361+
what_perma = f"the {content.plugin_type}'s terms"
362+
if len(content.full_keys[0]) > 1:
363+
what_title = "nested term field {subkey} for the"
364+
what_perma = f"this nested field of the {content.plugin_type}'s term"
365+
plugin_name = _plugin_name(content.fqcn, content.plugin_type)
345366
self.state.document.note_explicit_target(node)
346367
std = t.cast(StandardDomain, self.env.get_domain("std"))
347-
for rst_id, (html_id, key) in rst_ids.items():
368+
for rst_id, (html_id, key, subkey) in rst_ids.items():
369+
rst_title = f"{what_title.format(key=key, subkey=subkey)} {plugin_name}"
348370
std.note_hyperlink_target(
349371
rst_id,
350372
self.env.docname,
351373
html_id,
352-
f"{key} option of {_plugin_name(content.fqcn, content.plugin_type)}",
374+
rst_title,
353375
)
354376
permalink = nodes.raw(
355377
"",
356378
f' <a class="ansibleOptionLink" href="#{html_ids[0]}"'
357-
' title="Permalink to this option"></a>',
379+
f' title="Permalink to {what_perma}"></a>',
358380
format="html",
359381
)
360382
return [node, permalink]
@@ -377,19 +399,32 @@ def _run(self, content_str: str, content: AnsibleReturnValue) -> list[nodes.Node
377399
classes=["ansible-option-title"],
378400
ids=html_ids,
379401
)
402+
what_title = "{key} return value of"
403+
what_perma = "this return value"
404+
if content.special == "facts":
405+
what_title = "{key} returned fact of"
406+
what_perma = "this returned fact"
407+
if content.special == "return-value":
408+
what_title = "return value of the"
409+
what_perma = f"the {content.plugin_type}'s return value"
410+
if len(content.full_keys[0]) > 1:
411+
what_title = "nested return value field {subkey} of the"
412+
what_perma = f"this nested return value of this {content.plugin_type}"
413+
plugin_name = _plugin_name(content.fqcn, content.plugin_type)
380414
self.state.document.note_explicit_target(node)
381415
std = t.cast(StandardDomain, self.env.get_domain("std"))
382-
for rst_id, (html_id, key) in rst_ids.items():
416+
for rst_id, (html_id, key, subkey) in rst_ids.items():
417+
ref_title = f"{what_title.format(key=key, subkey=subkey)} {plugin_name}"
383418
std.note_hyperlink_target(
384419
rst_id,
385420
self.env.docname,
386421
html_id,
387-
f"{key} return value of {_plugin_name(content.fqcn, content.plugin_type)}",
422+
ref_title,
388423
)
389424
permalink = nodes.raw(
390425
"",
391426
f' <a class="ansibleOptionLink" href="#{html_ids[0]}"'
392-
' title="Permalink to this return value"></a>',
427+
f' title="Permalink to {what_perma}"></a>',
393428
format="html",
394429
)
395430
return [node, permalink]

‎src/sphinx_antsibull_ext/schemas/ansible_plugin.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,9 @@ class AnsibleOption(p.BaseModel):
4747
role_entrypoint: t.Optional[str] = None
4848
name: str
4949
full_keys: list[list[str]]
50+
special: t.Union[
51+
t.Literal["positional"], t.Literal["input"], t.Literal["terms"], None
52+
] = None
5053

5154

5255
class AnsibleReturnValue(p.BaseModel):
@@ -55,3 +58,4 @@ class AnsibleReturnValue(p.BaseModel):
5558
role_entrypoint: t.Optional[str] = None
5659
name: str
5760
full_keys: list[list[str]]
61+
special: t.Union[t.Literal["facts"], t.Literal["return-value"], None] = None

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

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -488,9 +488,6 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
488488
full_keys:
489489
- ["bar"]
490490

491-
.. raw:: html
492-
:url: data:text/plain;base64,IA==
493-
494491
.. ansible-option-type-line::
495492

496493
:ansible-option-type:`string`

‎tests/functional/baseline-default/collections/ns2/col/bar_filter.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ This describes the input of the filter, the value before ``| ns2.col.bar``.
9898
name: "Input"
9999
full_keys:
100100
- ["_input"]
101+
special: input
101102

102103
.. ansible-option-type-line::
103104

@@ -154,6 +155,7 @@ example: ``input | ns2.col.bar(positional1, positional2, ...)``
154155
name: "foo"
155156
full_keys:
156157
- ["foo"]
158+
special: positional
157159

158160
.. ansible-option-type-line::
159161

@@ -188,6 +190,7 @@ example: ``input | ns2.col.bar(positional1, positional2, ...)``
188190
name: "bar"
189191
full_keys:
190192
- ["bar"]
193+
special: positional
191194

192195
.. ansible-option-type-line::
193196

@@ -353,9 +356,7 @@ Return Value
353356
name: "Return value"
354357
full_keys:
355358
- ["_value"]
356-
357-
.. raw:: html
358-
:url: data:text/plain;base64,IA==
359+
special: return-value
359360

360361
.. ansible-option-type-line::
361362

‎tests/functional/baseline-default/collections/ns2/col/bar_test.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ This describes the input of the test, the value before ``is ns2.col.bar`` or ``i
9696
name: "Input"
9797
full_keys:
9898
- ["_input"]
99+
special: input
99100

100101
.. ansible-option-type-line::
101102

@@ -176,9 +177,7 @@ Return Value
176177
name: "Return value"
177178
full_keys:
178179
- ["_value"]
179-
180-
.. raw:: html
181-
:url: data:text/plain;base64,IA==
180+
special: return-value
182181

183182
.. ansible-option-type-line::
184183

‎tests/functional/baseline-default/collections/ns2/col/foo2_module.rst

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -339,9 +339,6 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
339339
full_keys:
340340
- ["bar"]
341341

342-
.. raw:: html
343-
:url: data:text/plain;base64,IA==
344-
345342
.. ansible-option-type-line::
346343

347344
:ansible-option-type:`string`

‎tests/functional/baseline-default/collections/ns2/col/foo_filter.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ This describes the input of the filter, the value before ``| ns2.col.foo``.
9898
name: "Input"
9999
full_keys:
100100
- ["_input"]
101+
special: input
101102

102103
.. ansible-option-type-line::
103104

@@ -264,9 +265,7 @@ Return Value
264265
name: "Return value"
265266
full_keys:
266267
- ["_value"]
267-
268-
.. raw:: html
269-
:url: data:text/plain;base64,IA==
268+
special: return-value
270269

271270
.. ansible-option-type-line::
272271

‎tests/functional/baseline-default/collections/ns2/col/foo_lookup.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ Terms
9696
name: "Terms"
9797
full_keys:
9898
- ["_terms"]
99+
special: terms
99100

100101
.. ansible-option-type-line::
101102

@@ -237,9 +238,7 @@ Return Value
237238
name: "Return value"
238239
full_keys:
239240
- ["_raw"]
240-
241-
.. raw:: html
242-
:url: data:text/plain;base64,IA==
241+
special: return-value
243242

244243
.. ansible-option-type-line::
245244

‎tests/functional/baseline-default/collections/ns2/col/foo_module.rst

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -490,9 +490,6 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
490490
full_keys:
491491
- ["bar"]
492492

493-
.. raw:: html
494-
:url: data:text/plain;base64,IA==
495-
496493
.. ansible-option-type-line::
497494

498495
:ansible-option-type:`string`

0 commit comments

Comments
 (0)