o nnh/;@sddlmZddlmZmZmZddlmZddlm Z ddl m Z ddlmZmZmZddlmZddlmZdd lmZdd lmZdd lmZeZd d ZddZd"ddZd"ddZ d"ddZ!d#ddZ"ddZ#ddZ$ddZ%d d!Z&dS)$) annotations)MutableMapping MutableSetMutableSequence)Path) constants) __version__) AnsibleErrorAnsibleParserErrorAnsiblePluginNotFound) string_types) to_native)read_docstring) AnsibleLoader)DisplaycCs|D]B\}}||vrBt||tr|||n't||tr*|||nt||tr.process_deprecationcsJ|D] }t|ts qd|vr|ddt|dtr"|dqdS)N version_addedversion_added_collection deprecated)rrget) specifiers specifier)r&r(rrprocess_option_specifiers1s   z>_process_versions_and_dates..process_option_specifierscs|D]Z}t|ts qd|vr|ddsPt|dtr&|dt|dtr4|dt|dtrB|dt|dtrP|dt|dtr^|dqdS)Nr)r*envinivarsr+ suboptions)valuesrrr,list)optionsoption)r&r'r(r/process_optionsrrr8:s$        z4_process_versions_and_dates..process_optionscsN|D] }t|ts qd|vr|ddt|dtr$|dqdS)Nr)r*contains)r4rrr,) return_values return_value)r&process_return_valuesrrr<Ls    z:_process_versions_and_dates..process_return_valuescs2|D]}t|ts qd|vr|ddqdS)Nr)r*)r4rr) attributes attribute)r&rrprocess_attributesUs   z7_process_versions_and_dates..process_attributesr)r*r+T)r%r6r=F)rr,r)fragmentr' return_docsr&r?r)r&r'r(r/r8r<r_process_versions_and_dates%s&     rCFcfdd}t||||dS)Ncs||vr ||<dSdSNrr6r7collection_name_fieldr rrrns z1add_collection_to_versions_and_dates..addrC)rAr r'rBrrrHr$add_collection_to_versions_and_datesm rJcrD)Ncs||kr ||=dSdSrE)r,rFrHrrremovevs zAremove_current_collection_from_versions_and_dates..removerI)rAr r'rBrLrrHr1remove_current_collection_from_versions_and_datesurKrMc Csj|dg}t|tr|d}g}|D] }|}d}||} | dur?d|vr?|dd} | d}| d}||} | durI||qt | |d} | dur_|dkr]||qd} t | |d } t | d } d| vr|d | ddd nd }t | ||d d | vr| d }|rd |vrg|d <|d |d| vr| d}|rd|vrg|d<|d|d| vrd| vrtd||fdD]7}|| vr||vrz t||| |Wqty}z tdt||||fd}~ww| |||<qzt|| Wqty"}z tdt|||fd}~ww|r3td|td |dS)Nextends_documentation_fragment, DOCUMENTATION.rz{}) file_name ansible_namer'notesseealsor6r=zJmissing options or attributes in fragment (%s), possibly misformatted?: %s)r6r=z%s %s (%s) of unknown type: %sz%s (%s) of unknown type: %sz(unknown doc_fragment(s) in file {0}: {1}z, )poprr splitstripr,rsplitupperappendgetattrrget_single_datajoinrJextendrrr r format)docfilenamefragment_loaderr' fragmentsunknown_fragments fragment_slug fragment_name fragment_varfragment_class splitname fragment_yamlrAreal_fragment_namereal_collection_namerXrYdoc_keyerrr add_fragments}sx            $   rtNcCs|dur|dur d}n|dk}n t|||d}|ddr5|dur+t|d||dt|d|||d|ddrI|durIt|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_errorsrerW)rgr' returndocsT)r'rB plainexamplesmetadata)rr,rJrt)rfrgrvrwr r' plugin_typedatarrr get_docstrings   r}c st|}z^tjd}|ds|d7}|dr|dd}tdtdkr1t d td d d}d d r[t fd d dDsYtdkr[ddvr[d}d |||WSt y|}zd |t|WYd}~Sd}~ww)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 DOCSITE_ROOT_URL/rRNrQzinvalid version ({0})z{0}.{1}rrU0c3s|] }|dvVqdS)rUNr).0pre split_verrr sz(get_versioned_doclink..)abdevdevelz {0}{1}/{2}z7(unable to create versioned doc link for path {0}: {1})) r Cconfigget_config_valueendswith startswithansible_versionr[len RuntimeErrorrdanyr)pathbase_url doc_versionexrrrget_versioned_doclinks&       .rcCsft|}|dd}|j|kr||}g}|D]}||}||kr%q|r0|t|q|S)NrQ)rr[stem with_name with_suffixexistsr_r )rplugin extensionsadjacentplugin_base_namepathsext candidaterrr_find_adjacents   rcCs|j|ddd}|r |js|dvr||\}}|r|js%td||dt|j}|jtjvr@t ||tj}|r=|dnd}nt |}|durNt d |||fS) zn if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding 'sidecar' file for docs FT)ignore_deprecated check_aliases)filtertestz%s was not found)plugin_load_contextrNzO%s cannot contain DOCUMENTATION nor does it have a companion documentation file) find_plugin_with_contextresolvedget_with_contextr rplugin_resolved_pathsuffixrDOC_EXTENSIONSrr r )rr{loadercontext plugin_objdocfile filenamesrfrrrfind_plugin_docfile&s    rc Csg}t|||\}}|j}z t|||||d}Wnty.} z td||f| dd} ~ ww|dsit||tjD].} zt| ||||d}| }|ddurQWnWq:tyh} z td||f| dd} ~ ww|ddurwtd||f||dd<||dd<|j|dd <|S) N)rvr r{z1%s did not contain a DOCUMENTATION attribute (%s))orig_excrz?Adjacent file %s did not contain a DOCUMENTATION attribute (%s)z&No documentation available for %s (%s)rf collection plugin_name) rplugin_resolved_collectionr}rr rrr resolved_fqcn) rr{rrgrvdocsrfrr rsnewfilerrrget_plugin_docs?s6    rr@)FFNNN)' __future__rcollections.abcrrrpathlibransiblerransible.releaserransible.errorsr r r ansible.module_utils.sixr +ansible.module_utils.common.text.convertersr ansible.parsing.plugin_docsransible.parsing.yaml.loaderransible.utils.displayrdisplayrrCrJrMrtr}rrrrrrrrs,          H   R "