o oax @sDdZddlZddlZddlZddlZddlZddlZddlmZddlmZddl m Z ddl m Z m Z mZmZmZmZmZddlmZddlmZmZmZdd lmZdd lmZmZmZdd lm Z ddl!Z!dd l!m"Z"dd l#m$Z$ddl%m&Z&ddl'm(Z(m)Z)m*Z*ddl+m,Z,ddl-m.Z.ddl/m0Z0m1Z1ddl2m3Z3m4Z4ddl5m6Z6ddl7m8Z8ddl9m:Z:ddl;mZ>m?Z?ddl@mAZAddlBmCZCmDZDddlEmFZFmGZGmHZHmIZImJZJddlKmLZLddlMmNZNddlOmPZPddlQmRZReCSeTZUeVd ZWeVd!ZXd"ZYGd#d$d$ejZZ[d%e$d&ej\d'dfd(d)Z]d*ej^d+e[d'dfd,d-Z_d*ej^d+ed'dfd.d/Z`Gd0d1d1ejZZad*eRd+ead'dfd2d3Zbe*d4d5die)iGd6d7d7ZcGd8d9d9e3Zdd%e$d:e d;e d'ee1fdd?d?eGZfd@egd'egfdAdBZhd@egd'egfdCdDZidgdFegdGejd'egfdHdIZkdJeegdKe d'egfdLdMZl E NdhdOegdPeegdGejdQegd'egf dRdSZmdTe,d'eegfdUdVZndgfdWegdXeegd'eege e egffdYdZZodWegd'ee e egffd[d\ZpdgfdWegdXeegd'eege e egffd]d^ZqGd_d`d`eHZrd%e$d'egfdadbZsd%e$d'dfdcddZtd%e$d'e ege ffdedfZudS)ia sphinx.ext.autosummary ~~~~~~~~~~~~~~~~~~~~~~ Sphinx extension that adds an autosummary:: directive, which can be used to generate function/method/attribute/etc. summary lists, similar to those output eg. by Epydoc and other API doc generation tools. An :autolink: role is also provided. autosummary directive --------------------- The autosummary directive has the form:: .. autosummary:: :nosignatures: :toctree: generated/ module.function_1 module.function_2 ... and it generates an output table (containing signatures, optionally) ======================== ============================================= module.function_1(args) Summary line from the docstring of function_1 module.function_2(args) Summary line from the docstring ... ======================== ============================================= If the :toctree: option is specified, files matching the function names are inserted to the toctree with the given prefix: generated/module.function_1 generated/module.function_2 ... Note: The file names contain the module:: or currentmodule:: prefixes. .. seealso:: autosummary_generate.py autolink role ------------- The autolink role functions as ``:obj:`` when the name referred can be resolved to a Python object, and otherwise it becomes simple emphasis. This can be used as the default role to make links 'smart'. :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. N) Parameter)path) ModuleType)AnyDictListOptionalTupleTypecast)nodes)ElementNodesystem_message) directives)RSTStateMachineStruct state_classes) StringList)addnodes)Sphinx)Config)RemovedInSphinx50WarningRemovedInSphinx60Warningdeprecated_alias)BuildEnvironment)TocTree) INSTANCEATTR Documenter)DocumenterBridgeOptions) import_module)mock)__)Project)ModuleAnalyzer PycodeError)SphinxComponentRegistry)loggingrst) NullReporterSphinxDirective SphinxRole new_documentswitch_source_input)signature_from_str)Matcher) OptionSpec)HTMLTranslatorz \.(?:\s+)z::\s*$)zet al.z i.e.c@ eZdZdS)autosummary_tocN__name__ __module__ __qualname__r9r9A/usr/lib/python3/dist-packages/sphinx/ext/autosummary/__init__.pyr4kr4appdoctreereturncsHtjdtdd|jjid dtdtddffd d |dS) ziInsert items described in autosummary:: to the TOC tree, but do not generate the toctree:: list. z'process_autosummary_toc() is deprecated) stacklevelnodedepthr>Nc sd|<t|D]<\}}zt|tr't|dtjr'tj|dWqWn ty1Yqwt|t j s9q|vrD||dqdS)NTrrA) enumerate isinstancer4rtoctreernotedocname IndexErrorr section)rBrCjsubnode crawl_toccrawledenvr9r:rNxs$   z*process_autosummary_toc..crawl_toc)rA)warningswarnrbuilderrPr int)r<r=r9rMr:process_autosummary_tocos  rUselfrBcCstj)z-Hide autosummary toctree list in HTML output.)r SkipNoderVrBr9r9r:autosummary_toc_visit_htmlsrYcCsdSNr9rXr9r9r:autosummary_noopsr[c@r3)autosummary_tableNr5r9r9r9r:r\r;r\c CszXttj|d}ttj|d}ttj|d}tttj|}|D]2}ttj|d}ttj|d}t t |D]\} } t | tj rT| dd} t | || <q;q#WdStybYdSw)z0Make the first column of the table non-breaking.r  N)r r tabletgrouptbodyrrowentry paragraphrDlistrETextastextreplacerI) rVrBr`rarbrowsrc col1_entryparrKrLnew_textr9r9r:autosummary_table_visit_htmls$  rnzsphinx.ext.autosummary_appc@seZdZddZdS)FakeApplicationcCs8d|_d|_i|_d|_t|_tdd|_t|_ dSrZ) doctreedirevents extensionssrcdirrconfigr$projectr'registry)rVr9r9r:__init__s  zFakeApplication.__init__N)r6r7r8rxr9r9r9r:rps rpcseZdZdfdd ZZS) FakeDirectiver>NcsXtdd}t|d}t}|jddddt|}t|d}t|dtd|dS) N) tab_width)settingsautodoc_class_signaturemixedT)documentr)rrpruaddrsuperrxr )rVr|rr<rPstate __class__r9r:rxs   zFakeDirective.__init__)r>N)r6r7r8rx __classcell__r9r9rr:rysryobjparentcsddlm}m}tr|S|durt||d}n|}t|dr)|t|jn|tdfdd|j j D}|rK|j dd d |d S|S) zGet an autodoc.Documenter class suitable for documenting the given object. *obj* is the Python object to be documented, and *parent* is an another Python object (e.g. a module or a class) to which *obj* belongs to. r)DataDocumenterModuleDocumenterNr6cs g|] }|ddr|qS)rF)can_document_member).0clsr parent_docr9r: s z"get_documenter..cS|jSrZ)priority)rr9r9r:z get_documenter..)keyr]) sphinx.ext.autodocrrinspectismoduleget_documenterhasattrryr6rw documentersvaluessort)r<rrrrparent_doc_clsclassesr9rr:rs   rc @seZdZUdZdZdZdZdZej ej ej ej ej dZ e ed<deefdd Zd ed eedeeeeeffd d Zdededededdf ddZdeedeeeeeeffddZdeeeeeefdeefddZdS) Autosummaryz Pretty table containing short signatures and summaries of functions etc. autosummary can also optionally generate a hidden toctree:: node. rFT)captionrF nosignatures recursivetemplate option_specr>cCst|j|jjjt|j|j|_dd|jD}| |}| |}d|j vrt |jj}|j d}g}t|jj}|jj}|D]C\} } } } || | } t || } t t || } | |jjvr||j| drrtd}ntd}tj|| |dqC|| qC|rt}||d<dd|D|d <d |d <d|d <|j d |d <|t dd|d|j vrd |j vrtjtd|d d|S)NcSs8g|]}|rtd|dr|dqS)z ^[~a-zA-Z_]r)stripresearchsplitrxr9r9r:rs z#Autosummary.run..rFz5autosummary references excluded document %r. Ignored.zMautosummary: stub file not found %r. Check your autosummary_generate setting.location includefilescSsg|]}d|fqSrZr9)rdocnr9r9r:r%sentriesr]maxdepthglobrrz;A captioned autosummary requires :toctree: option. ignored.)!rrPrrreporterr linenobridgecontent get_items get_tableoptions posixpathdirnamerHrr0ruexclude_patternsautosummary_filename_mapgetjoinnormpath found_docsdoc2pathr#loggerwarning get_locationappendrrFr4)rVnamesitemsr r tree_prefixdocnamesexcluded filename_mapnamesigsummary real_namerHmsgtocnoder9r9r:runsH           zAutosummary.runrprefixesc Cst|jj9z t||WWdSty>}zzt||WWYd}~WdSty9Y|wd}~ww1sBwYdSrZ)r"ruautosummary_mock_importsimport_by_name ImportErrorimport_ivar_by_name)rVrrexcr9r9r:r2s  zAutosummary.import_by_namer<rr full_namercCst|||}||j|S)zGet an autodoc.Documenter class suitable for documenting the given object. Wraps get_documenter and is meant as a hook for extensions. )rr)rVr<rrrdocclsr9r9r:create_documenter?s  zAutosummary.create_documenterrc Cs4t|j}g}d}|D] }|}|dr"|dd}|dd}z |j||d\}}} } WntyDtjtd|| d Yq wt |j _ |} t |ts_| d | t| dd} ||jj|| | } | stjtd || d ||d d |fq | stjtd || d ||d d |fq | jjr| sq zt| | _| jWnty} ztd| d| _WYd} ~ nd} ~ wwz| jdd}Wn t y| }Ynw|sd }nt!d|t|}t"||d}| #dt$|j j j%dd|j&j'}|||||fq |S)z}Try to import the given names, and return a list of ``[(name, signature, summary_string, real_name), ...]``. 2~rAN.r])rz autosummary: failed to import %srz::zfailed to parse name %srzfailed to import object %sz$[autodoc] module analyzer failed: %sF)show_annotation  max_chars)(get_import_prefixes_from_envrP startswithrrrrrr#rrrresultrErlenrr< parse_namer import_objectrmembers check_moduler% for_moduleget_real_modnameanalyzerfind_attr_docsr&debugformat_signature TypeErrormaxmangle_signature add_contentextract_summarydatarr)rVrrrmax_item_charsr display_namerrrmodnamer documentererrrrrr9r9r:rIst               zAutosummary.get_itemsrcst}d|d<td}tjddgd}||tjddd}|||tjddd |tjdd d td|d t d d ffdd }|D]'\}}} } d} dj vrjd| || t |f} nd| || f} | } || | qQ||gS)zGenerate a proper list of table nodes for autosummary:: directive. *items* is a list produced by :meth:`get_items`. z\X{1}{2}\X{1}{2}specr longtablerr?)colsr)colwidthZ column_textsr>Nc std}j\}}|D]S}td}t}||d||ftj|1j |d|zt |dtjr>|d}Wn t yHYnw|t d|Wdn1s\wYq|dS)Nrz%s:%d:r) r rc state_machineget_source_and_linererrr.r nested_parserErIrd)rrcsourcelinetextrBvlbodyrVr9r: append_rows&   z)Autosummary.get_table..append_rowrrz:py:%s:`%s <%s>`\ %sz:py:%s:`%s <%s>`) rtabular_col_specr\r r`rracolspecrbstrrr)escape)rVr table_specr` real_tablegroupr rrrr qualifiercol1col2r9r r:rs(      zAutosummary.get_tableN)r6r7r8__doc__required_argumentsoptional_argumentsfinal_argument_whitespace has_contentrunchanged_required unchangedflagrr1__annotations__rrrrr rrrrrrr9r9r9r:rs. &0  & *PrscCs|ddS)z+Strip a type hint from argument definition.:r)rr)r!r9r9r:strip_arg_typehintsr#cCsz>t|}t|j}t|D]!\}}|jtjur!|jtjd}|j tjur-|jdd}|||<q|j|tjd}t |WSt yI|YSw)zCClean up signature using inspect.signautre() for mangle_signature()) annotationN)default) parametersreturn_annotation) r/rfr&rrDr$remptyrir%r Exception)r!rr&iparamr9r9r:_cleanup_signatures      r,rrc Cst|}tdd|}tdd|}tdd|}tdd|}tdd|}td d|}td d|}td |rJtd d|}td |s=td |r]td d|}td |sPtd |rptd d|}td |scg}g}td}|r||}|s|d}n|d|d|ddd}|s{t |D] \}}t |||<qt |D] \}} t | ||<qt d||dd}|r|sdt d||dd}d|St ||dddkr|dt d||t |ddd7}d|S)z5Reformat a function signature to a more compact form.z \)\s*->\s.*$)z ^\((.*)\)$z\1z\\\\rz\\'z\\"z'[^']*'z"[^"]*"z \([^)]*\)z<[^>]*>z{[^}]*}z^(.*, |)([a-zA-Z0-9_*]+)\s*=\s*z, rr?rANrz[%s]z[, %s]z(%s)) r,rsubrrcompilerinsertrrDr# limited_joinr) rrr!argsoptsopt_remr*argoptr9r9r:rsT          rdocrcCspdttdtdtjfdd}|r#|ds#|d|r#|drt|D]\}}|s7|d|}nq'|gkr>dS|||j}t |dtj rU|d }n[t |dtj sd|d}nLt d |}t|d kry|d}n7d}tt|D].}d |d|d d d }g|dd<|||j}|trqt|tjsnqtd |}|S) zExtract summary from docstring.r<r|r>cSs,ttd}td|}t|_||||S)NBodyr)rrr-r*rr)r<r|rrBr9r9r:parses   zextract_summary..parserNrr^rAz. r)rrrr rrpoprDr|rErJrhre periods_rerrrrangerstripendswithWELL_KNOWN_ABBREVIATIONSrftraverser literal_rer2)r<rr>r*piecerBr sentencesr9r9r:rs>         r...seproverflow_markerc Cs~||}t||kr |Sd}d}t|D]\}}|t|t|7}||t|kr0|d7}q|t|d||gS)zJoin a number of strings into one, limiting the length to *max_chars*. If the string overflows this limit, replace the last fitting item by *overflow_marker*. Returns: joined_string rrAN)rrrDrf) rJrrrKfull_strn_charsn_itemsrKitemr9r9r:r5Ts  r5rPcCs^dg}|jd}|r|d||jd}|r-|r'|d|d||S|d||S)z` Obtain current Python import prefixes (for `import_by_name`) from ``document.env`` Nz py:modulerzpy:classr) ref_contextrr4)rPr currmodule currclassr9r9r:ros    rrrc Cstg}|D],}z|rd||g}n|}t|\}}}||||fWSty0||Yqwtdd|)z~Import a Python object that has the given *name*, under one of the *prefixes*. The first name that succeeds is used. rzno module named %sz or )r_import_by_namerr)rrtriedprefix prefixed_namerrrr9r9r:rs rc CsHz|d}d|dd}|r.zt|}t||d||fWWStttfy-Ynwd}d}ttdt |dD]$}|}d|d|}zt|Wn tyYYq=w|t j vranq=|t |krd}t j |}||dD] }|}t||}qu|||fWSt j |d|fWSt ttt fy} zt| j| d} ~ ww)z+Import a Python object given its full name.rNr]rrA)rrr!getattrrrIAttributeErrorreversedrArsysmodules ValueErrorKeyErrorr6) r name_partsrmodlast_jrKrrobj_nameer9r9r:rSsF         rSc CszB|dd\}}t||\}}}}||dd}tt|d|}|||f|jvs5||f|jvr@|d|t ||fWSWt t t t fyOYt w)zImport an instance variable that has the given *name*, under one of the *prefixes*. The first name that succeeds is used. rrArr7) rsplitrrir%rrWanalyze attr_docs annotationsrrr\r&) rrattrrrrrqualnamerr9r9r:rsrc@s.eZdZdZdeeeeeffddZdS)AutoLinkzSmart linking role. Expands to ':obj:`text`' if `text` is an object that can be imported; otherwise expands to '*text*'. r>cCs|jdd}|d|j|j|j|j|j|j\}}|r!||fSt |dks)Jt t j |d}zt |j}t|d|W||fStyet tj|d}tj|j||dd|d<Y||fSw)NpyrrAr reftargetrr)rP get_domainrolerawtextr rinlinerrrrr r pending_xrefrrrr literalemphasisrh)rV pyobj_roleobjectserrorsrprrqr9r9r:rs&    z AutoLink.runN) r6r7r8rr rrrrr9r9r9r:ris"ricsHdtdttdfffdd }d}jjD] }d||vr!|SqdS)Nsuffixr>.cs"j|}|durdS|jS)N)restructuredtext)rwget_source_parsersr supported)rv parser_classr<r9r:get_supported_formatsz,get_rst_suffix..get_supported_formatrw)rr ru source_suffix)r<r|rvr9r{r:get_rst_suffixs  r~c s&|jj}|dur|jjfddjD}n4|durn/t|jjfdd|D}|ddD]}tt |j |sJt t d|||q1|sOdSt|}|dur`t t ddSdd lm}|jj}t|jj||||j |||jj|jjd WddS1swYdS) NTcs,g|]}tj|rj|ddqS)N)base)osrisfilerr)rPr9r:rsz,process_generate_options..Fcs*g|]}||tsdndqS)rr)rCtuple)rgenfile)extr9r:r s"z(autosummary_generate: file not found: %szbautosummary generats .rst files internally. But your source_suffix does not contain .rst. Skipped.r)generate_autosummary_docs)rv base_pathr<imported_members overwriteencoding)ruautosummary_generaterSrPrrfr}rrrrtrrr#remover~sphinx.ext.autosummary.generaterautosummary_imported_membersr"rautosummary_generate_overwritesource_encoding)r<genfilesrdrvrrr9)rPrr:process_generate_optionss<     "rcCs|d|jtttfttfttfttfttfd|jtttfttfttfttfttfd|dt| dt | dt | did| did | d ddttg| d dd | d ddd| dgd tgtjddS)Nzsphinx.ext.autodoc)htmllatexr mantexinfo autosummaryautolinkzbuilder-initedautosummary_contextTrrrrFrcSrrZ)autodoc_mock_imports)rur9r9r:r;rzsetup..rPr)versionparallel_read_safe)setup_extensionadd_noder4rYr[r\rn add_directiveradd_rolericonnectradd_config_valueboolrfsphinx__display_version__r{r9r9r:setup$s6    r)r-)r-rI)vrrrrrrZrQrrtypesrtypingrrrrr r r docutilsr docutils.nodesr rrdocutils.parsers.rstrdocutils.parsers.rst.statesrrrdocutils.statemachinerrrsphinx.applicationr sphinx.configrsphinx.deprecationrrrsphinx.environmentr#sphinx.environment.adapters.toctreerrrrsphinx.ext.autodoc.directiverr sphinx.ext.autodoc.importerr!sphinx.ext.autodoc.mockr" sphinx.localer#sphinx.projectr$ sphinx.pycoder%r&sphinx.registryr' sphinx.utilr(r)sphinx.util.docutilsr*r+r,r-r.sphinx.util.inspectr/sphinx.util.matchingr0sphinx.util.typingr1sphinx.writers.htmlr2 getLoggerr6rr3r@rFrDcommentr4rrU NodeVisitorrYr[r\rnrpryrrrr#r,rTrrr5rrrSrrir~rrr9r9r9r:s6   $                       %Z;8 ,,)&