a )g:@sddlmZmZmZeZddlmZmZm Z ddl m Z ddl m ZddlmZddlmZmZmZddlmZddlmZdd lmZdd lmZdd lmZeZ d d Z!ddZ"d"ddZ#d#ddZ$d$ddZ%d%ddZ&ddZ'ddZ(ddZ)d d!Z*dS)&)absolute_importdivisionprint_function)MutableMapping MutableSetMutableSequence)Path) constants) __version__) AnsibleErrorAnsibleParserErrorAnsiblePluginNotFound) string_types) to_native)read_docstring) AnsibleLoader)DisplaycCs|D]\}}||vrt||tr6|||nNt||trT|||n0t||trxtt|||}n t d||||<qdS)Nz?Attempt to extend a documentation fragment, invalid type for %s) items isinstancerupdateraddrsorted frozenset Exception)targetsourcekeyvaluer=/usr/lib/python3.9/site-packages/ansible/utils/plugin_docs.pymerge_fragments r csdfdd fddfddfdd fd d }|sTdS|rd|dSd |vrx|d d t|dtr|dddt|dtr|dt|dtr||ddS)NFcsj|rdnd}t|tsdSs"|r6d|vr6|d|d|vrJ|d|sf|sfd|vrf|d|dS)NZremoved_from_collectioncollection_nameZ removed_inZremoved_at_dateversion)rr)Z deprecation top_levelr!)callback is_modulerrprocess_deprecation's    z8_process_versions_and_dates..process_deprecationcsJ|D]@}t|tsqd|vr(|ddt|dtr|dqdS)N version_addedversion_added_collection deprecated)rrget)Z specifiersZ specifier)r$r&rrprocess_option_specifiers2s  z>_process_versions_and_dates..process_option_specifierscs|D]}t|tsqd|vr,|ddst|dtrL|dt|dtrh|dt|dtr|dt|dtr|dt|dtr|dqdS)Nr'r(envZinivarsr)Z suboptions)valuesrrr*list)optionsoption)r$r%r&r+process_optionsrrr2;s        z4_process_versions_and_dates..process_optionscsN|D]@}t|tsqd|vr,|ddt|dtr|dqdS)Nr'r(contains)r.rrr*)Z return_valuesZ return_value)r$process_return_valuesrrr4Ms   z:_process_versions_and_dates..process_return_valuescs2|D]$}t|tsqd|vr|ddqdS)Nr'r()r.rr) attributesZ attribute)r$rrprocess_attributesVs   z7_process_versions_and_dates..process_attributesr'r(r)T)r#r0r5)F)rr*r)fragmentr% return_docsr$r6r)r$r%r&r+r2r4r_process_versions_and_dates&s$     r9Fcsfdd}t||||dS)Ncs||vr||<dSNrr0r1Zcollection_name_fieldr!rrrosz1add_collection_to_versions_and_dates..addr9)r7r!r%r8rrr<r$add_collection_to_versions_and_datesns r>csfdd}t||||dS)Ncs||kr||=dSr:)r*r;r<rrremovewszAremove_current_collection_from_versions_and_dates..remover=)r7r!r%r8r?rr<r1remove_current_collection_from_versions_and_datesvs r@c Cs|dg}t|tr|g}g}|D]J}|}d}||} | durvd|vrv|dd} | d}| d}||} | dur||q$t| |d} | dur|dkr||q$nd} t| |d } t| d} d| vrd | ddd nd }t | ||d d | vr>| d }|r>d |vr0g|d <|d  |d | vrx| d }|rxd |vrjg|d <|d  |d| vrd| vrtd||fdD]}|| vr||vrzt||| |Wn>ty}z$tdt||||fWYd}~n d}~00n| |||<qzt|| Wq$tyn}z"tdt|||fWYd}~q$d}~00q$|rtd|td |dS)NZextends_documentation_fragmentZ DOCUMENTATION.rz{}) file_nameZ ansible_namer%notesseealsor0r5zJmissing options or attributes in fragment (%s), possibly misformatted?: %s)r0r5z%s %s (%s) of unknown type: %sz%s (%s) of unknown type: %sz(unknown doc_fragment(s) in file {0}: {1}z, )poprrr*rsplitupperappendgetattrrZget_single_datajoinsplitr>extendrr r rformat)docfilenamefragment_loaderr%Z fragmentsZunknown_fragmentsZ fragment_slugZ fragment_nameZ fragment_varZfragment_classZ splitnameZ fragment_yamlr7Zreal_fragment_nameZreal_collection_namerGrHZdoc_keyerrr add_fragments~sl           $        0.rVNcCs|dur |durd}q |dk}nt|||d}|ddrh|durTt|d||dt|d|||d|ddr|durt|d||d d |d|d |d|d fS) z DOCUMENTATION can be extended using documentation fragments loaded by the PluginLoader from the doc_fragments plugins. NFmodule)verbose ignore_errorsrRrF)rTr%Z returndocsT)r%r8Z plainexamplesmetadata)rr*r>rV)rSrTrXrYr!r% plugin_typedatarrr get_docstrings   r]c st|}ztjd}|ds(|d7}|dr>|dd}tdtdkrbt d td d d}d d rt fd d dDstdkrddvrd}d |||WSt y}zd |t|WYd}~Sd}~00dS)a returns a versioned documentation link for the current Ansible major.minor version; used to generate in-product warning/error links to the configured DOCSITE_ROOT_URL (eg, https://docs.ansible.com/ansible/2.8/somepath/doc.html) :param path: relative path to a document under docs/docsite/rst; :return: absolute URL to the specified doc for the current version of Ansible ZDOCSITE_ROOT_URL/rBNrAzinvalid version ({0})z{0}.{1}rrD0c3s|]}|dvVqdS)rDNr).0ZpreZ split_verrr z(get_versioned_doclink..)abdevZdevelz {0}{1}/{2}z7(unable to create versioned doc link for path {0}: {1})) rCZconfigZget_config_valueendswith startswithansible_versionrOlen RuntimeErrorrQanyr)pathZbase_urlZ doc_versionexrrbrget_versioned_doclinks"       .rqcCsft|}|dd}|j|kr*||}g}|D].}||}||krJq2|r2|t|q2|S)NrA)rrOstem with_name with_suffixexistsrLr)roplugin extensionsZadjacentZplugin_base_namepathsext candidaterrr_find_adjacents   r|cCs|j|ddd}|r|js0|dvr0||\}}|r:|jsJtd||dt|j}|jtjvrt ||tj}|rz|dnd}nt |}|durt d |||j fS) zn if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding 'sidecar' file for docs FT)Zignore_deprecatedZ check_aliases)filtertestz%s was not found)Zplugin_load_contextrNzO%s cannot contain DOCUMENTATION nor does it have a companion documentation file) Zfind_plugin_with_contextZresolvedZget_with_contextr rZplugin_resolved_pathsuffixrhDOC_EXTENSIONSr|rr Zplugin_resolved_collection)rwr[loadercontextZ plugin_objZdocfile filenamesrSrrrfind_plugin_docfile's    rc Cs"g}t|||\}}zt|||||d}Wn8tyb}z td||f|dWYd}~n d}~00|dst||tjD]j} z,t| ||||d}| }|ddurWqWqzty}z td||f|dWYd}~qzd}~00qz|ddurtd||fn||dd<||dd<|S) N)rXr!r[z1%s did not contain a DOCUMENTATION attribute (%s))Zorig_excrz?Adjacent file %s did not contain a DOCUMENTATION attribute (%s)z&No documentation available for %s (%s)rSZ collection)rr]rr r|rhr) rwr[rrTrXZdocsrSr!rUZnewfilerrrget_plugin_docs@s(*  ,  r)F)F)F)FFNNN)+Z __future__rrrtypeZ __metaclass__collections.abcrrrpathlibrZansibler rhZansible.releaser rkZansible.errorsr r r Zansible.module_utils.sixrZansible.module_utils._textrZansible.parsing.plugin_docsrZansible.parsing.yaml.loaderrZansible.utils.displayrZdisplayr r9r>r@rVr]rqr|rrrrrrs,        H   R "