Package: doc-helper
UseDocHelperto simplify your python docstringsIf you have been writing classes or functions with many shared arguments, you
might have going through the tedious and error prone process of copy-pasting,
searching-updating same docstring again and again. Passing through**kwargsmight not always be the solution not to say it's implicit and makes user to
look up multiple documents to find available arguments.So how about one place to store and update them all?DocHelperkeeps the
docstrings for arguments in the same place and you only need to write the
template for each class or functions - it will compose and fill in the
template in Google format.Works from Jupyter notebook to Sphinx where docstrings were read by importing.InstallationInstall usingpip(recommended)pipinstalldoc-helperInstall from source# make sure you have setuptools and wheel installedgitclonehttps://github.com/ynshen/DocHelper.gitcdDocHelper
pythonsetup.pybdist_wheel
pipinstalldist/the-wheel-file-of-your-version.whlUsageInitialize aDocHelperwith argument docstringsfromdoc_helperimportDocHelpermy_doc=DocHelper(arg1='Just an simple argument',# defined as keyword argumentsarg2=('Also an simple argument'),# or a (not really) tuplearg3=('int','This argument is integer')# tuple with data type)Add arguments when you neededmy_doc.add(arg4=('pd.DataFrame','Just a new argument'))UseDocHelper.get()to get formatted docstring for arguments# Pass a list/tuple of argument names to `DocHelper.get()`>>>my_doc.get(['arg1','arg3'])arg1:Justansimpleargumentarg3(int):Thisargumentisinteger# Pass a callable (function) to automatic find related arguments (except 'self')defawesome_function(arg1,arg3):pass>>>my_doc.get(awesome_function)arg1:Justansimpleargumentarg3(int):ThisargumentisintegerUse decoratorDocHelper.composeto write templateSimply write a string with comma separated arguments name in<<and>>.
Default indents is 4, just add a number to change to desired indents.# Example 1@my_doc.compose("""This is my awesome functionArgs:<<arg1, arg2>>arg3: This arg3 is special""")defawesome_function(arg1,arg2,arg3):pass>>>awesome_function.__doc__ThisismyawesomefunctionArgs:arg1:Justansimpleargumentarg2:Alsoansimpleargumentarg3:Thisarg3isspecial# Example 2@my_doc.compose("""This is another awesome function only takes arg1, arg3, and I want indent = 8Args:<<arg1, arg2, 8>>""")defanother_awesome_function(arg1,arg3):pass>>>another_awesome_function.__doc__Thisisanotherawesomefunctiononlytakesarg1,arg3,andIwandindent=8Args:arg1:Justansimpleargumentarg3(int):Thisargumentisinteger# Example 3@my_doc.compose("""Feeling lazy? left it blank to include all arguments (except 'self')Args:<<>>""")defanother_another_awesome_function(arg1,arg2,arg3):pass>>>another_another_awesome_function.__doc__ThisismyawesomefunctionArgs:arg1:Justansimpleargumentarg2:Alsoansimpleargumentarg3(int):ThisargumentisintegerUpdateversion 1.1.1: indents at the top of<<  >>can be controlled throughDocHelper.compose(indent_at_top=False/True), default False.version 1.1.0: extra indents at the top of each lines were subtractedTODOAdd docstring formatting function to subtract extra indentsInclude different formatting (Numpy, reStructuredText)