use versioned doclink for url references (#74245)

* use versioned doclink for url references

Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
Brian Coca 2021-04-26 13:07:38 -04:00 committed by GitHub
parent 85e7108d52
commit c1879a5011
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 20 additions and 7 deletions

View file

@ -0,0 +1,4 @@
bugfixes:
- ansible-doc will now correcty handle relative refs to 'current' ansible version
- set_fact module, removed hardcoded url to relative reference
- user module, removed hardcoded url to relative reference

View file

@ -5,7 +5,6 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
import datetime
import json import json
import pkgutil import pkgutil
import os import os
@ -24,7 +23,7 @@ from ansible.cli.arguments import option_helpers as opt_help
from ansible.collections.list import list_collection_dirs from ansible.collections.list import list_collection_dirs
from ansible.errors import AnsibleError, AnsibleOptionsError, AnsibleParserError from ansible.errors import AnsibleError, AnsibleOptionsError, AnsibleParserError
from ansible.module_utils._text import to_native, to_text from ansible.module_utils._text import to_native, to_text
from ansible.module_utils.common._collections_compat import Container, Sequence from ansible.module_utils.common._collections_compat import Sequence
from ansible.module_utils.common.json import AnsibleJSONEncoder from ansible.module_utils.common.json import AnsibleJSONEncoder
from ansible.module_utils.common.yaml import yaml_dump from ansible.module_utils.common.yaml import yaml_dump
from ansible.module_utils.compat import importlib from ansible.module_utils.compat import importlib
@ -38,7 +37,6 @@ from ansible.utils.collection_loader._collection_finder import _get_collection_n
from ansible.utils.display import Display from ansible.utils.display import Display
from ansible.utils.plugin_docs import ( from ansible.utils.plugin_docs import (
REJECTLIST, REJECTLIST,
remove_current_collection_from_versions_and_dates,
get_docstring, get_docstring,
get_versioned_doclink, get_versioned_doclink,
) )
@ -286,6 +284,13 @@ class RoleMixin(object):
return result return result
def _doclink(url):
# assume that if it is relative, it is for docsite, ignore rest
if not url.startswith(("http", "..")):
url = get_versioned_doclink(url)
return url
class DocCLI(CLI, RoleMixin): class DocCLI(CLI, RoleMixin):
''' displays information on modules installed in Ansible libraries. ''' displays information on modules installed in Ansible libraries.
It displays a terse listing of plugins and their short descriptions, It displays a terse listing of plugins and their short descriptions,
@ -323,8 +328,6 @@ class DocCLI(CLI, RoleMixin):
t = cls._ITALIC.sub(r"`\1'", text) # I(word) => `word' t = cls._ITALIC.sub(r"`\1'", text) # I(word) => `word'
t = cls._BOLD.sub(r"*\1*", t) # B(word) => *word* t = cls._BOLD.sub(r"*\1*", t) # B(word) => *word*
t = cls._MODULE.sub("[" + r"\1" + "]", t) # M(word) => [word] 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._REF.sub(r"\1", t) # R(word, sphinx-ref) => word
t = cls._CONST.sub("`" + r"\1" + "'", t) # C(word) => `word' t = cls._CONST.sub("`" + r"\1" + "'", t) # C(word) => `word'
t = cls._RULER.sub("\n{0}\n".format("-" * 13), t) # HORIZONTALLINE => ------- t = cls._RULER.sub("\n{0}\n".format("-" * 13), t) # HORIZONTALLINE => -------
@ -334,6 +337,12 @@ class DocCLI(CLI, RoleMixin):
t = cls._NOTES.sub(r" Note:", t) # nicer note t = cls._NOTES.sub(r" Note:", t) # nicer note
t = cls._SEEALSO.sub(r"", t) # remove seealso t = cls._SEEALSO.sub(r"", t) # remove seealso
# handle docsite refs
# U(word) => word
t = re.sub(cls._URL, lambda m: r"%s" % _doclink(m.group(1)), t)
# L(word, url) => word <url>
t = re.sub(cls._LINK, lambda m: r"%s <%s>" % (m.group(1), _doclink(m.group(2))), t)
return t return t
def init_parser(self): def init_parser(self):

View file

@ -31,7 +31,7 @@ options:
- This boolean converts the variable into an actual 'fact' which will also be added to the fact cache, if fact caching is enabled. - This boolean converts the variable into an actual 'fact' which will also be added to the fact cache, if fact caching is enabled.
- Normally this module creates 'host level variables' and has much higher precedence, this option changes the nature and precedence - Normally this module creates 'host level variables' and has much higher precedence, this option changes the nature and precedence
(by 7 steps) of the variable created. (by 7 steps) of the variable created.
U(https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable) U(user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable)
- "This actually creates 2 copies of the variable, a normal 'set_fact' host variable with high precedence and - "This actually creates 2 copies of the variable, a normal 'set_fact' host variable with high precedence and
a lower 'ansible_fact' one that is available for persistance via the facts cache plugin. a lower 'ansible_fact' one that is available for persistance via the facts cache plugin.
This creates a possibly confusing interaction with C(meta: clear_facts) as it will remove the 'ansible_fact' but not the host variable." This creates a possibly confusing interaction with C(meta: clear_facts) as it will remove the 'ansible_fact' but not the host variable."

View file

@ -89,7 +89,7 @@ options:
- On macOS systems, this value has to be cleartext. Beware of security issues. - On macOS systems, this value has to be cleartext. Beware of security issues.
- To create a disabled account on Linux systems, set this to C('!') or C('*'). - To create a disabled account on Linux systems, set this to C('!') or C('*').
- To create a disabled account on OpenBSD, set this to C('*************'). - To create a disabled account on OpenBSD, set this to C('*************').
- See L(FAQ entry,https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module) - See L(FAQ entry, reference_appendices/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module)
for details on various ways to generate these password values. for details on various ways to generate these password values.
type: str type: str
state: state: