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.
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
Update ansible doc formats #71070
Update ansible doc formats #71070
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
minor_changes: | ||
- ansible-doc will now format, ``L()``, ``R()``, and ``HORIZONTALLINE`` in | ||
plugin docs just as the website docs do. https://github.com/ansible/ansible/pull/71070 | ||
- Fixed ansible-doc to not substitute for words followed by parenthesis. For | ||
instance, ``IBM(International Business Machines)`` will no longer be | ||
substituted with a link to a non-existent module. | ||
https://github.com/ansible/ansible/pull/71070 |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -8,6 +8,7 @@ | |
import datetime | ||
import json | ||
import os | ||
import re | ||
import textwrap | ||
import traceback | ||
import yaml | ||
|
@@ -71,11 +72,36 @@ class DocCLI(CLI): | |
# default ignore list for detailed views | ||
IGNORE = ('module', 'docuri', 'version_added', 'short_description', 'now_date', 'plainexamples', 'returndocs', 'collection') | ||
|
||
# Warning: If you add more elements here, you also need to add it to the docsite build (in the | ||
# ansible-community/antsibull repo) | ||
_ITALIC = re.compile(r"\bI\(([^)]+)\)") | ||
_BOLD = re.compile(r"\bB\(([^)]+)\)") | ||
_MODULE = re.compile(r"\bM\(([^)]+)\)") | ||
_LINK = re.compile(r"\bL\(([^)]+), *([^)]+)\)") | ||
_URL = re.compile(r"\bU\(([^)]+)\)") | ||
_REF = re.compile(r"\bR\(([^)]+), *([^)]+)\)") | ||
_CONST = re.compile(r"\bC\(([^)]+)\)") | ||
_RULER = re.compile(r"\bHORIZONTALLINE\b") | ||
|
||
def __init__(self, args): | ||
|
||
super(DocCLI, self).__init__(args) | ||
self.plugin_list = set() | ||
|
||
@classmethod | ||
def tty_ify(cls, text): | ||
|
||
t = cls._ITALIC.sub(r"`\1'", text) # I(word) => `word' | ||
t = cls._BOLD.sub(r"*\1*", t) # B(word) => *word* | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This may not matter because something else may handle the RST --> HTML conversion, but for in RST, There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This isn't rst. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. rst and html (for building the web docs) are handled by rst_ify and html_ify from this code: https://github.com/ansible-community/antsibull/blob/main/antsibull/jinja2/filters.py The code in this PR is only for ansible-doc to output to the screen. This split is why I added the note that the code in both places needs to be changed if new macros are added. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ah, ok. I figured they were separate and this was only for There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fun times with cross project relationships. 😁 |
||
t = cls._MODULE.sub("[" + r"\1" + "]", t) # M(word) => [word] | ||
t = cls._URL.sub(r"\1", t) # U(word) => word | ||
t = cls._LINK.sub(r"\1 <\2>", t) # L(word, url) => word <url> | ||
t = cls._REF.sub(r"\1", t) # R(word, sphinx-ref) => word | ||
t = cls._CONST.sub("`" + r"\1" + "'", t) # C(word) => `word' | ||
t = cls._RULER.sub("\n{0}\n".format("-" * 13), t) # HORIZONTALLINE => ------- | ||
|
||
return t | ||
|
||
def init_parser(self): | ||
|
||
coll_filter = 'A supplied argument will be used for filtering, can be a namespace or full collection name.' | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
# Make coding more python3-ish | ||
from __future__ import (absolute_import, division, print_function) | ||
__metaclass__ = type | ||
|
||
import pytest | ||
|
||
from ansible.cli.doc import DocCLI | ||
|
||
|
||
TTY_IFY_DATA = { | ||
# No substitutions | ||
'no-op': 'no-op', | ||
'no-op Z(test)': 'no-op Z(test)', | ||
# Simple cases of all substitutions | ||
'I(italic)': "`italic'", | ||
'B(bold)': '*bold*', | ||
'M(ansible.builtin.module)': '[ansible.builtin.module]', | ||
'U(https://docs.ansible.com)': 'https://docs.ansible.com', | ||
'L(the user guide,https://docs.ansible.com/user-guide.html)': 'the user guide <https://docs.ansible.com/user-guide.html>', | ||
'R(the user guide,user-guide)': 'the user guide', | ||
'C(/usr/bin/file)': "`/usr/bin/file'", | ||
'HORIZONTALLINE': '\n{0}\n'.format('-' * 13), | ||
# Multiple substitutions | ||
'The M(ansible.builtin.yum) module B(MUST) be given the C(package) parameter. See the R(looping docs,using-loops) for more info': | ||
"The [ansible.builtin.yum] module *MUST* be given the `package' parameter. See the looping docs for more info", | ||
# Problem cases | ||
'IBM(International Business Machines)': 'IBM(International Business Machines)', | ||
'L(the user guide, https://docs.ansible.com/)': 'the user guide <https://docs.ansible.com/>', | ||
'R(the user guide, user-guide)': 'the user guide', | ||
} | ||
|
||
|
||
@pytest.mark.parametrize('text, expected', sorted(TTY_IFY_DATA.items())) | ||
def test_ttyify(text, expected): | ||
assert DocCLI.tty_ify(text) == expected |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I thought parameters should use
C()
so they are formatted as inline code. That's just my personal preference, though.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Uh oh, lots of things for you to correct, then ;-)