Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 4 commits into from
Oct 6, 2022
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6aa309d
Use <code> for default values, sample values, and choice values.
felixfontein Sep 23, 2022
ff785e0
Also format samples.
felixfontein Sep 25, 2022
057f094
Update baseline tests.
felixfontein Oct 3, 2022
0cf1c09
Also ignore official roles.
felixfontein Oct 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions changelogs/fragments/42-code-rendering.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)."
12 changes: 6 additions & 6 deletions src/antsibull_docs/data/docsite/macros/choiceslist.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}
Expand All @@ -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 %}
Expand All @@ -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:] %}
Expand All @@ -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 %}
Expand Down
2 changes: 1 addition & 1 deletion src/antsibull_docs/data/docsite/macros/parameters.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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']) %}
Expand Down
4 changes: 2 additions & 2 deletions src/antsibull_docs/data/docsite/macros/returnvalues.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}


Expand Down Expand Up @@ -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>
Expand Down
3 changes: 1 addition & 2 deletions src/antsibull_docs/data/docsite/plugin.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 1 addition & 2 deletions src/antsibull_docs/data/docsite/role.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion src/antsibull_docs/lint_extra_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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
Expand Down
3 changes: 3 additions & 0 deletions src/antsibull_docs/lint_plugin_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
)
Expand Down Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions src/sphinx_antsibull_ext/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@


from .assets import setup_assets
from .roles import setup_roles


def setup(app):
Expand All @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion src/sphinx_antsibull_ext/antsibull-minimal.css
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion src/sphinx_antsibull_ext/css/antsibull-minimal.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand Down
Loading