Use <code> for default values, sample values, and choice values (#42)

* Use <code> for default values, sample values, and choice values.

* Also format samples.

* Update baseline tests.

* Also ignore official roles.

Author: felixfontein

Diff for: changelogs/fragments/42-code-rendering.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Use code formatting for all values, such as choice entries, defaults, and samples (https://github.com/ansible-community/antsibull-docs/issues/38, https://github.com/ansible-community/antsibull-docs/pull/42)."

Diff for: src/antsibull_docs/data/docsite/macros/choiceslist.rst.j2

@@ -8,7 +8,7 @@
 {%   if choices is mapping %}
 {%     for choice, desc in choices | dictsort %}
 {%       if not has_no_default and ((default_value is not list and default_value == choice) or (default_value is list and choice in default_value)) %}
-      - :ansible-option-default-bold:`@{ choice | antsibull_to_json | rst_escape(escape_ending_whitespace=true) }@` :ansible-option-default:`(default)`\ :
+      - :ansible-option-choices-entry-default:`@{ choice | antsibull_to_json | rst_escape(escape_ending_whitespace=true) }@` :ansible-option-choices-default-mark:`(default)`\ :
 {%       else %}
       - :ansible-option-choices-entry:`@{ choice | antsibull_to_json | rst_escape(escape_ending_whitespace=true) }@`\ :
 {%       endif %}
@@ -20,7 +20,7 @@
 {%   else %}
 {%     for choice in choices %}
 {%       if not has_no_default and ((default_value is not list and default_value == choice) or (default_value is list and choice in default_value)) %}
-      - :ansible-option-default-bold:`@{ choice | antsibull_to_json | rst_escape(escape_ending_whitespace=true) }@` :ansible-option-default:`← (default)`
+      - :ansible-option-choices-entry-default:`@{ choice | antsibull_to_json | rst_escape(escape_ending_whitespace=true) }@` :ansible-option-choices-default-mark:`← (default)`
 {%       else %}
       - :ansible-option-choices-entry:`@{ choice | antsibull_to_json | rst_escape(escape_ending_whitespace=true) }@`
 {%       endif %}
@@ -35,9 +35,9 @@
 {%     for choice, desc in choices | dictsort %}
         <li>
 {%       if not has_no_default and ((default_value is not list and default_value == choice) or (default_value is list and choice in default_value)) %}
-          <p><span class="ansible-option-default-bold">@{ choice | antsibull_to_json | escape }@</span> <span class="ansible-option-default">(default)</span>:
+          <p><code class="ansible-value literal notranslate ansible-option-default-bold">@{ choice | antsibull_to_json | escape }@</code> <span class="ansible-option-choices-default-mark">(default)</span>:
 {%       else %}
-          <p><span class="ansible-option-choices-entry">@{ choice | antsibull_to_json | escape }@</span>:
+          <p><code class="ansible-value literal notranslate ansible-option-choices-entry">@{ choice | antsibull_to_json | escape }@</code>:
 {%       endif %}
           @{ desc | first | default('') | html_ify | indent(10, blank=true) }@</p>
 {%       for line in desc[1:] %}
@@ -48,9 +48,9 @@
 {%   else %}
 {%     for choice in choices %}
 {%       if not has_no_default and ((default_value is not list and default_value == choice) or (default_value is list and choice in default_value)) %}
-        <li><p><span class="ansible-option-default-bold">@{ choice | antsibull_to_json | escape }@</span> <span class="ansible-option-default">← (default)</span></p></li>
+        <li><p><code class="ansible-value literal notranslate ansible-option-default-bold">@{ choice | antsibull_to_json | escape }@</code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
 {%       else %}
-        <li><p><span class="ansible-option-choices-entry">@{ choice | antsibull_to_json | escape }@</span></p></li>
+        <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">@{ choice | antsibull_to_json | escape }@</code></p></li>
 {%       endif %}
 {%     endfor %}
 {%   endif %}

Diff for: src/antsibull_docs/data/docsite/macros/parameters.rst.j2

@@ -225,7 +225,7 @@
 {%   endif %}
 {#   Show default value, when multiple choice or no choices #}
 {%   if value['default'] is not none and value['default'] not in value['choices'] %}
-      <p class="ansible-option-line"><span class="ansible-option-default-bold">Default:</span> <span class="ansible-option-default">@{ value['default'] | antsibull_to_json | escape | indent(6, blank=true) }@</span></p>
+      <p class="ansible-option-line"><span class="ansible-option-default-bold">Default:</span> <code class="ansible-value literal notranslate ansible-option-default">@{ value['default'] | antsibull_to_json | escape | indent(6, blank=true) }@</code></p>
 {%   endif %}
 {#   Configuration #}
 {%   if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}

Diff for: src/antsibull_docs/data/docsite/macros/returnvalues.rst.j2

@@ -84,7 +84,7 @@
       .. rst-class:: ansible-option-line
       .. rst-class:: ansible-option-sample
 
-      :ansible-option-sample-bold:`Sample:` @{ value['sample'] | antsibull_to_json | rst_escape | indent(6) }@
+      :ansible-option-sample-bold:`Sample:` :ansible-rv-sample-value:`@{ value['sample'] | antsibull_to_json | rst_escape(escape_ending_whitespace=true) | indent(6, blank=true) }@`
 {%   endif %}
 
 
@@ -145,7 +145,7 @@
 @{     choices_html(value['choices'], has_no_default=True) }@
 {%   endif %}
 {%   if value['sample'] is not none %}
-      <p class="ansible-option-line ansible-option-sample"><span class="ansible-option-sample-bold">Sample:</span> @{ value['sample'] | antsibull_to_json | escape | indent(6, blank=true) }@</p>
+      <p class="ansible-option-line ansible-option-sample"><span class="ansible-option-sample-bold">Sample:</span> <code class="ansible-value literal notranslate ansible-option-sample">@{ value['sample'] | antsibull_to_json | escape | indent(6, blank=true) }@</code></p>
 {%   endif %}
     </div></td>
   </tr>

Diff for: src/antsibull_docs/data/docsite/plugin.rst.j2

@@ -32,8 +32,7 @@
 .. role:: ansible-option-versionadded
 .. role:: ansible-option-aliases
 .. role:: ansible-option-choices
-.. role:: ansible-option-choices-entry
-.. role:: ansible-option-default
+.. role:: ansible-option-choices-default-mark
 .. role:: ansible-option-default-bold
 .. role:: ansible-option-configuration
 .. role:: ansible-option-returned-bold

Diff for: src/antsibull_docs/data/docsite/role.rst.j2

@@ -20,8 +20,7 @@
 .. role:: ansible-option-versionadded
 .. role:: ansible-option-aliases
 .. role:: ansible-option-choices
-.. role:: ansible-option-choices-entry
-.. role:: ansible-option-default
+.. role:: ansible-option-choices-default-mark
 .. role:: ansible-option-default-bold
 
 {# If we can put together source and github repo, we could make the Edit me of github button work.

Diff for: src/antsibull_docs/lint_extra_docs.py

@@ -10,6 +10,8 @@
 import re
 import typing as t
 
+from sphinx_antsibull_ext import roles as antsibull_roles
+
 from .extra_docs import (
     find_extra_docs,
     lint_required_conditions,
@@ -33,7 +35,7 @@ def lint_optional_conditions(content: str, path: str, collection_name: str
 
     Return a list of errors.
     '''
-    return check_rst_content(content, filename=path)
+    return check_rst_content(content, filename=path, ignore_roles=list(antsibull_roles.ROLES))
 
 
 def lint_collection_extra_docs_files(path_to_collection: str

Diff for: src/antsibull_docs/lint_plugin_docs.py

@@ -15,6 +15,8 @@
 from antsibull_core.compat import asyncio_run
 from antsibull_core.venv import FakeVenvRunner
 
+from sphinx_antsibull_ext import roles as antsibull_roles
+
 from .lint_helpers import (
     load_collection_info,
 )
@@ -161,6 +163,7 @@ def _lint_collection_plugin_docs(collections_dir: str, collection_name: str,
                 rst_results = check_rst_content(
                     rst_content, filename=path,
                     ignore_directives=['rst-class'],
+                    ignore_roles=list(antsibull_roles.ROLES),
                 )
                 result.extend([(path, result[0], result[1], result[2]) for result in rst_results])
     return result

Diff for: src/sphinx_antsibull_ext/__init__.py

@@ -14,6 +14,7 @@
 
 
 from .assets import setup_assets
+from .roles import setup_roles
 
 
 def setup(app):
@@ -25,6 +26,9 @@ def setup(app):
     # Add assets
     setup_assets(app)
 
+    # Add roles
+    setup_roles(app)
+
     return dict(
         parallel_read_safe=True,
         parallel_write_safe=True,

Diff for: src/sphinx_antsibull_ext/antsibull-minimal.css

@@ -172,7 +172,7 @@ table.ansible-option-table {
   .ansible-option-choices-entry {
   }
 
-  .ansible-option-default {
+  .ansible-option-default, .ansible-option-choices-default-mark {
     color: blue;
   }