Improve generated markup; add styling for LaTeX output

changelogs/fragments/199-roles-directives.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - "Move roles from templates and structural styling from stylesheet to antsibull Sphinx extension. This makes sure that HTML tags such as ``<strong>`` and ``<em>`` are used for bold and italic texts, and that the same formattings are used for the LaTeX builder (https://github.com/ansible-community/antsibull-docs/pull/199)."
+  - "Use same colors for LaTeX builder's output as for HTML builder's output (https://github.com/ansible-community/antsibull-docs/pull/199)."

src/antsibull_docs/data/docsite/ansible-docsite/macros/choiceslist.rst.j2

@@ -35,7 +35,7 @@
 {%     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><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><code class="ansible-value literal notranslate ansible-option-default-bold"><strong>@{ choice | antsibull_to_json | escape }@</strong></code> <span class="ansible-option-choices-default-mark">(default)</span>:
 {%       else %}
           <p><code class="ansible-value literal notranslate ansible-option-choices-entry">@{ choice | antsibull_to_json | escape }@</code>:
 {%       endif %}
@@ -48,7 +48,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)) %}
-        <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>
+        <li><p><code class="ansible-value literal notranslate ansible-option-default-bold"><strong>@{ choice | antsibull_to_json | escape }@</strong></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
 {%       else %}
         <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">@{ choice | antsibull_to_json | escape }@</code></p></li>
 {%       endif %}

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

@@ -42,18 +42,16 @@
       .. raw:: html
 
         <a class="ansibleOptionLink" href="#parameter-@{ parameter_html_prefix }@{% for part in value['full_key'] %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this option"></a>
-{%   if value['aliases'] %}
 
-      .. rst-class:: ansible-option-type-line
+      .. ansible-option-type-line::
+{%   if value['aliases'] %}
 
-      :ansible-option-aliases:`aliases: @{ value['aliases']|join(', ') }@`
+        :ansible-option-aliases:`aliases: @{ value['aliases']|join(', ') }@`
 {%   endif %}
 
-      .. rst-class:: ansible-option-type-line
-
-      :ansible-option-type:`@{ value['type'] | documented_type }@`
-      {%- if value['type'] == 'list' and value['elements'] is not none %} / :ansible-option-elements:`elements=@{ value['elements'] | documented_type }@`{% endif -%}
-      {%- if value['required'] %} / :ansible-option-required:`required`{% endif %}
+        :ansible-option-type:`@{ value['type'] | documented_type }@`
+        {%- if value['type'] == 'list' and value['elements'] is not none %} / :ansible-option-elements:`elements=@{ value['elements'] | documented_type }@`{% endif -%}
+        {%- if value['required'] %} / :ansible-option-required:`required`{% endif %}
 {%-   if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %}
 
 
@@ -204,7 +202,7 @@
 {%   endif %}
       </p>
 {%   if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %}
-      <p><span class="ansible-option-versionadded">added in @{ version_added_html(value['version_added'], value['version_added_collection'] or collection) }@</span></p>
+      <p><em class="ansible-option-versionadded">added in @{ version_added_html(value['version_added'], value['version_added_collection'] or collection) }@</em></p>
 {%   endif %}
 {%   if plugin_type != 'module' %}
 @{     deprecates_html(value['deprecated'], collection, role_entrypoint=role_entrypoint) }@
@@ -221,16 +219,16 @@
 {%   endif %}
 {#   Show possible choices and highlight details #}
 {%   if value['choices'] %}
-      <p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
+      <p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
 @{     choices_html(value['choices'], value['default'], role_entrypoint=role_entrypoint) }@
 {%   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> <code class="ansible-value literal notranslate ansible-option-default">@{ value['default'] | antsibull_to_json | escape | indent(6, blank=true) }@</code></p>
+      <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <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']) %}
-      <p class="ansible-option-line"><span class="ansible-option-configuration">Configuration:</span></p>
+      <p class="ansible-option-line"><strong class="ansible-option-configuration">Configuration:</strong></p>
       <ul class="simple">
 {%     if value['ini'] %}
       <li>
@@ -243,7 +241,7 @@
   <span class="l l-Scalar l-Scalar-Plain">@{ ini['key'] | escape }@ = @{ value['default'] | antsibull_to_ini_value | escape }@</span></pre></div></div>
 {%         endif %}
 {%         if ini['version_added'] is still_relevant(collection=ini['version_added_collection'] or collection) %}
-        <p><span class="ansible-option-versionadded">added in @{ version_added_html(ini['version_added'], ini['version_added_collection'] or collection) }@</span></p>
+        <p><em class="ansible-option-versionadded">added in @{ version_added_html(ini['version_added'], ini['version_added_collection'] or collection) }@</em></p>
 {%         endif %}
 @{         deprecates_html(ini['deprecated'], collection, role_entrypoint=role_entrypoint) }@
 {%       endfor %}
@@ -253,7 +251,7 @@
       <li>
         <p>Environment variable: <code class="xref std std-envvar literal notranslate">@{ env['name'] | escape }@</code></p>
 {%       if env['version_added'] is still_relevant(collection=env['version_added_collection'] or collection) %}
-        <p><span class="ansible-option-versionadded">added in @{ version_added_html(env['version_added'], env['version_added_collection'] or collection) }@</span></p>
+        <p><em class="ansible-option-versionadded">added in @{ version_added_html(env['version_added'], env['version_added_collection'] or collection) }@</em></p>
 {%       endif %}
 @{       deprecates_html(env['deprecated'], collection, role_entrypoint=role_entrypoint) }@
       </li>
@@ -262,7 +260,7 @@
       <li>
         <p>Variable: @{ myvar['name'] | escape }@</p>
 {%       if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %}
-        <p><span class="ansible-option-versionadded">added in @{ version_added_html(myvar['version_added'], myvar['version_added_collection'] or collection) }@</span></p>
+        <p><em class="ansible-option-versionadded">added in @{ version_added_html(myvar['version_added'], myvar['version_added_collection'] or collection) }@</em></p>
 {%       endif %}
 @{       deprecates_html(myvar['deprecated'], collection, role_entrypoint=role_entrypoint) }@
       </li>
@@ -271,7 +269,7 @@
       <li>
         <p>Keyword: @{ kw['name'] | escape }@</p>
 {%       if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %}
-        <p><span class="ansible-option-versionadded">added in @{ version_added_html(kw['version_added'], kw['version_added_collection'] or collection) }@</span></p>
+        <p><em class="ansible-option-versionadded">added in @{ version_added_html(kw['version_added'], kw['version_added_collection'] or collection) }@</em></p>
 {%       endif %}
 @{       deprecates_html(kw['deprecated'], collection, role_entrypoint=role_entrypoint) }@
       </li>
@@ -280,7 +278,7 @@
       <li>
         <p>CLI argument: @{ mycli['option'] | escape }@</p>
 {%       if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %}
-        <p><span class="ansible-option-versionadded">added in @{ version_added_html(mycli['version_added'], mycli['version_added_collection'] or collection) }@</span></p>
+        <p><em class="ansible-option-versionadded">added in @{ version_added_html(mycli['version_added'], mycli['version_added_collection'] or collection) }@</em></p>
 {%       endif %}
 @{       deprecates_html(mycli['deprecated'], collection, role_entrypoint=role_entrypoint) }@
       </li>

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

@@ -41,10 +41,10 @@
 
         <a class="ansibleOptionLink" href="#return-{% for part in value['full_key'] %}@{ part | urlencode }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this return value"></a>
 
-      .. rst-class:: ansible-option-type-line
+      .. ansible-option-type-line::
 
-      :ansible-option-type:`@{ value['type'] | documented_type }@`
-      {%- if value['type'] == 'list' and value['elements'] is not none %} / :ansible-option-elements:`elements=@{ value['elements'] | documented_type }@`{% endif %}
+        :ansible-option-type:`@{ value['type'] | documented_type }@`
+        {%- if value['type'] == 'list' and value['elements'] is not none %} / :ansible-option-elements:`elements=@{ value['elements'] | documented_type }@`{% endif %}
 {%-   if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %}
 
 
@@ -129,7 +129,7 @@
 {%   endif %}
       </p>
 {%   if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %}
-      <p><span class="ansible-option-versionadded">added in @{ version_added_html(value['version_added'], value['version_added_collection'] or collection) }@</span></p>
+      <p><em class="ansible-option-versionadded">added in @{ version_added_html(value['version_added'], value['version_added_collection'] or collection) }@</em></p>
 {%   endif %}
     </div></td>
 {#   description #}
@@ -138,15 +138,15 @@
       <p>@{ desc | html_ify(role_entrypoint=role_entrypoint) | indent(6, blank=true) }@</p>
 {%   endfor %}
 {%   if value['returned'] %}
-      <p class="ansible-option-line"><span class="ansible-option-returned-bold">Returned:</span> @{ value['returned'] | html_ify(role_entrypoint=role_entrypoint) | indent(6, blank=true) }@</p>
+      <p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> @{ value['returned'] | html_ify(role_entrypoint=role_entrypoint) | indent(6, blank=true) }@</p>
 {%   endif %}
 {#   Show possible choices and highlight details #}
 {%   if value['choices'] %}
-      <p class="ansible-option-line"><span class="ansible-option-choices">Can only return:</span></p>
+      <p class="ansible-option-line"><strong class="ansible-option-choices">Can only return:</strong></p>
 @{     choices_html(value['choices'], has_no_default=True, role_entrypoint=role_entrypoint) }@
 {%   endif %}
 {%   if value['sample'] is not none %}
-      <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>
+      <p class="ansible-option-line ansible-option-sample"><strong class="ansible-option-sample-bold">Sample:</strong> <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>

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

@@ -25,24 +25,6 @@
 .. |antsibull-internal-nbsp| unicode:: 0xA0
     :trim:
 
-.. role:: ansible-attribute-support-label
-.. role:: ansible-attribute-support-property
-.. role:: ansible-attribute-support-full
-.. role:: ansible-attribute-support-partial
-.. role:: ansible-attribute-support-none
-.. role:: ansible-attribute-support-na
-.. role:: ansible-option-type
-.. role:: ansible-option-elements
-.. role:: ansible-option-required
-.. role:: ansible-option-versionadded
-.. role:: ansible-option-aliases
-.. role:: ansible-option-choices
-.. role:: ansible-option-choices-default-mark
-.. role:: ansible-option-default-bold
-.. role:: ansible-option-configuration
-.. role:: ansible-option-returned-bold
-.. role:: ansible-option-sample-bold
-
 {# If we can put together source and github repo, we could make the Edit me of github button work.
    See meta.get("source") in Ansible's docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html
    for more information

src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2

@@ -17,21 +17,6 @@
 :github_url: @{ edit_on_github_url }@?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr
 {% endif %}
 
-.. role:: ansible-attribute-support-label
-.. role:: ansible-attribute-support-property
-.. role:: ansible-attribute-support-full
-.. role:: ansible-attribute-support-partial
-.. role:: ansible-attribute-support-none
-.. role:: ansible-attribute-support-na
-.. role:: ansible-option-type
-.. role:: ansible-option-elements
-.. role:: ansible-option-required
-.. role:: ansible-option-versionadded
-.. role:: ansible-option-aliases
-.. role:: ansible-option-choices
-.. 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.
    See meta.get("source") in Ansible's docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html
    for more information

src/antsibull_docs/lint_extra_docs.py

@@ -11,6 +11,7 @@
 import os.path
 import re
 
+from sphinx_antsibull_ext import directives as antsibull_directives
 from sphinx_antsibull_ext import roles as antsibull_roles
 
 from .extra_docs import (
@@ -36,7 +37,10 @@ def lint_optional_conditions(
     Return a list of errors.
     """
     return check_rst_content(
-        content, filename=path, ignore_roles=list(antsibull_roles.ROLES)
+        content,
+        filename=path,
+        ignore_directives=list(antsibull_directives.DIRECTIVES),
+        ignore_roles=list(antsibull_roles.ROLES),
     )
 
 

src/antsibull_docs/lint_plugin_docs.py

@@ -23,6 +23,7 @@
 from antsibull_docs_parser.parser import parse as parse_markup
 from jinja2 import Template
 
+from sphinx_antsibull_ext import directives as antsibull_directives
 from sphinx_antsibull_ext import roles as antsibull_roles
 
 from .augment_docs import augment_docs
@@ -643,7 +644,7 @@ def _lint_plugin_docs(
         rst_results = check_rst_content(
             rst_content,
             filename=path,
-            ignore_directives=["rst-class"],
+            ignore_directives=["rst-class"] + list(antsibull_directives.DIRECTIVES),
             ignore_roles=list(antsibull_roles.ROLES),
         )
         result.extend(

src/sphinx_antsibull_ext/__init__.py

@@ -9,13 +9,15 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.1"
-__license__ = "BSD license"
+# TODO: update version automatically
+__version__ = "2.4.0"
+__license__ = "GPL-3.0-or-later"
 __author__ = "Felix Fontein"
 __author_email__ = "felix@fontein.de"
 
 
 from .assets import setup_assets
+from .directives import setup_directives
 from .roles import setup_roles
 
 
@@ -31,6 +33,9 @@ def setup(app):
     # Add roles
     setup_roles(app)
 
+    # Add directives
+    setup_directives(app)
+
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,