"""Directive to generate a summary of listed objects."""from__future__importannotationsfromtypingimportAny,ClassVarfromdocutilsimportnodesfromdocutils.parsers.rstimportdirectivesfromsphinx.util.docutilsimportSphinxDirectivefromautodoc2.sphinx.utilsimport(get_all_analyser,get_database,load_config,nested_parse_generated,warn_sphinx,)fromautodoc2.utilsimportItemData,WarningSubtypes
[docs]classAutodocSummary(SphinxDirective):"""Directive to generate a summary of listed objects."""has_content=Truerequired_arguments=0optional_arguments=0final_argument_whitespace=Falseoption_spec:ClassVar[dict[str,Any]]={"renderer":directives.unchanged_required,}
[docs]defrun(self)->list[nodes.Node]:source,line=self.get_source_info()# warnings take the docname and line numberwarning_loc=(self.env.docname,line)all_resolver=get_all_analyser(self.env)# load the configurationoverrides={}if"renderer"inself.options:overrides={"render_plugin":self.options["renderer"]}config=load_config(self.env.app,overrides=overrides,location=warning_loc)db=get_database(self.env)objects:list[ItemData]=[]content_line:straliases:dict[str,str]={}forcontent_idx,content_lineinenumerate(self.content):parts=content_line.strip().split(maxsplit=1)iflen(parts)==0:continuefull_name=parts[0]alias:str|None=Noneiffull_name.startswith("~"):full_name=full_name[1:]alias=full_name.split(".")[-1]iflen(parts)>1:alias=parts[1]if(item:=db.get_item(full_name))isNoneand(resolved_name:=all_resolver.get_name(full_name)):item=db.get_item(resolved_name)ifitemisnotNone:forancestorindb.get_ancestors(full_name,include_self=True):ifancestorand"file_path"inancestor:iffile_path:=ancestor["file_path"]:self.env.note_dependency(file_path)breakifalias:aliases[item["full_name"]]=aliaseliffull_name!=item["full_name"]:aliases[item["full_name"]]=full_nameobjects.append(item)else:warn_sphinx(f"Could not find {full_name}",WarningSubtypes.NAME_NOT_FOUND,location=(self.env.docname,line+self.content_offset+1+content_idx,),)ifnotobjects:return[]# setup warningsdef_warn_render(msg:str,type_:WarningSubtypes)->None:warn_sphinx(msg,type_,location=warning_loc)# TODO it would be ideal to create this as nodes, rather than nested parsing,# but for now this is the simplest optioncontent=list(config.render_plugin(db,config,all_resolver=all_resolver,warn=_warn_render,standalone=True,).generate_summary(objects,alias=aliases))base=nested_parse_generated(self.state,content,source,line)returnbase.childrenor[]