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

Author: felixfontein

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)."

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 %}

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']) %}

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

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.

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

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,

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;
   }