Package: pardoc
pardocYet another docstring parser for python, usinglark-parserInstallationpipinstallpardocA quick look>>>frompardocimportgoogle_parser,pretty>>>docstring="""This is an example of a module level function.Function parameters should be documented in the ``Args`` section. The nameof each parameter is required. The type and description of each parameteris optional, but should be included if not obvious.If \*args or \*\*kwargs are accepted,they should be listed as ``*args`` and ``**kwargs``.The format for a parameter is::name (type): descriptionThe description may span multiple lines. Followinglines should be indented. The "(type)" is optional.Multiple paragraphs are supported in parameterdescriptions.Args:param1 (int): The first parameter.param2 (:obj:`str`, optional): The second parameter. Defaults to None.Second line of description should be indented.*args: Variable length argument list.**kwargs: Arbitrary keyword arguments.Returns:bool: True if successful, False otherwise.The return type is optional and may be specified at the beginning ofthe ``Returns`` section followed by a colon.The ``Returns`` section may span multiple lines and paragraphs.Following lines should be indented to match the first line.The ``Returns`` section supports any reStructuredText formatting,including literal blocks::{'param1': param1,'param2': param2}Raises:AttributeError: The ``Raises`` section is a list of all exceptionsthat are relevant to the interface.ValueError: If `param2` is equal to `param1`.""">>>parsed=google_parser.parse(docstring)>>>pretty(parsed,print_=True)ParsedSection(title=SUMMARY)ParsedPara(lines=1)Thisisanexampleofamodulelevelfunction.ParsedPara(lines=3)Functionparametersshouldbedocumentedinthe``Args``section.Thenameofeachparameterisrequired.Thetypeanddescriptionofeachparameterisoptional,butshouldbeincludedifnotobvious.ParsedPara(lines=2)If\*argsor\*\*kwargsareaccepted,theyshouldbelistedas``*args``and``**kwargs``.ParsedPara(lines=1)Theformatforaparameteris::ParsedPara(lines=2)ParsedPara(lines=1)name(type):descriptionParsedPara(lines=2)ParsedPara(lines=2)Thedescriptionmayspanmultiplelines.Followinglinesshouldbeindented.The"(type)"isoptional.ParsedPara(lines=2)Multipleparagraphsaresupportedinparameterdescriptions.ParsedSection(title=Args)ParsedItem(name=param1,type=int,desc=Thefirstparameter.)ParsedItem(name=param2,type=:obj:`str`,optional,desc=Thesecondparameter.DefaultstoNone.)ParsedPara(lines=1)Secondlineofdescriptionshouldbeindented.ParsedItem(name=*args,type=None,desc=Variablelengthargumentlist.)ParsedItem(name=**kwargs,type=None,desc=Arbitrarykeywordarguments.)ParsedSection(title=Returns)ParsedItem(name=bool,type=None,desc=Trueifsuccessful,Falseotherwise.)ParsedPara(lines=2)Thereturntypeisoptionalandmaybespecifiedatthebeginningofthe``Returns``sectionfollowedbyacolon.ParsedPara(lines=2)The``Returns``sectionmayspanmultiplelinesandparagraphs.Followinglinesshouldbeindentedtomatchthefirstline.ParsedPara(lines=2)The``Returns``sectionsupportsanyreStructuredTextformatting,includingliteralblocks::ParsedPara(lines=2)ParsedPara(lines=1){ParsedPara(lines=1)ParsedPara(lines=2)'param1':param1,'param2':param2ParsedPara(lines=1)ParsedPara(lines=1)}ParsedSection(title=Raises)ParsedItem(name=AttributeError,type=None,desc=The``Raises``sectionisalistofallexceptions)ParsedPara(lines=1)thatarerelevanttotheinterface.ParsedItem(name=ValueError,type=None,desc=If`param2`isequalto`param1`.)UsageParsing a known style docstringfrompardocimportgoogle_parser,numpy_parserparsed=google_parser(docstring)# orparsed=numpy_parser(docstring)Parsing an unknown style docstringfrompardocimportauto_parserparser=auto_parser(docstring)# parsing results from auto_parser is cached and reused.parsed=parser.parse(docstring)Parsed objectThere are 6 types of parsed objects, include the finalParsedobject that
attaches all sectionsThe first 5 are allnamedtuples:ParsedItem=namedtuple('ParsedItem',['name','type','desc','more'])ParsedTodo=namedtuple('ParsedTodo',['todo','more'])ParsedSection=namedtuple('ParsedSection',['title','section'])ParsedPara=namedtuple('ParsedPara',['lines'])ParsedCode=namedtuple('ParsedCode',['lang','codes'])TheParsedis an ordered dictionary (OrderedDiot) fromdiot, which
allows dot access to keys:fromdiotimportOrderedDiotclassParsed(OrderedDiot):"""Parsed object"""Formatting a parsed object to the original style>>>frompardocimportgoogle_parser>>>docstring="""Example function with types documented in the docstring.Args:param0: No typeparam1 (int): The first parameter.param2 (str): The second parameter.Returns:bool: The return value. True for success, False otherwise.""">>># note the arbitrary empty lines>>>reformatted=google_parser.format(docstring)>>># or>>>reformatted=google_parser.format(google_parser.parse(docstring))>>>print(reformatted)Examplefunctionwithtypesdocumentedinthedocstring.Args:param0:Notypeparam1(int):Thefirstparameter.param2(str):Thesecondparameter.Returns:bool:Thereturnvalue.Trueforsuccess,Falseotherwise.Pretty printing the parsed objectsSeeA quick look