Docstring Parsing

Note

It currently works for Google and Numpy docstrings, but it’s still a bit of a WIP.

It tries its best to preserve the surrounding whitespace, and it will separate out whitespace, below, above, and to the left (common indentation) of the text block, so you can edit the content of the block and the rest of it will be preserved.

import starstar.docstr as ssdoc

doc = ssdoc.parse('''This is my docstring description.

Args:
    a (str): this is a
    b (str): this is b
        yes its b
        yes b

I'm some more docs

Returns:
    dict: the special thing
    list: other

alksdfj
''')

# renders the docstring (looks the same as the input)
print(doc)

# see the breakdown of the different sections/parameters.
print(repr(doc))

doc['args'].append(doc.Param.new(
    'c', 'list',
    'this is c, that holds some values.\nsome more text.'))

assert str(doc) == '''This is my docstring description.

Args:
    a (str): this is a
    b (str): this is b
        yes its b
        yes b
    c (list): this is c, that holds some values.
        some more text.

I'm some more docs

Returns:
    dict: the special thing
    list: other

alksdfj
'''

class starstar.docstr.Block(text, title=None, name=None, kind=None, cleandoc=False, end_newline=True, raw=False, indent=0)

class starstar.docstr.Param(text, can_be_unnamed=False, block_kind=None, **kw)

Represents the text belonging to a single parameter.

Most of this code is just to facilitate the parsing, changing, and reformatting of the parameter data.

__init__(text, can_be_unnamed=False, block_kind=None, **kw)

__setattr__(k, v)

Implement setattr(self, name, value).

class starstar.docstr.Google(doc=None, name=None, cleandoc=True)

Google docstring parser.

ds = Google("""This is my docstring description.

Args:
    a (str): this is a



    b (str): this is b
        yes its b
        yes b

I'm some more docs

Returns:
    dict: the special thing
    list: other

alksdfj

.. code-block:: python

    print("this is something")

    print("hmm nice")


ksnkdsjkdsksd ljksdfkjl
asjkldf

.. code-block:: python

    print("neat!")
""")

class Param(text, can_be_unnamed=False, block_kind=None, **kw)

The Google parameter format.

{name} ({type}): {description}

class starstar.docstr.Numpy(doc=None, name=None, cleandoc=True)

Numpy docstring parser.

ds = Numpy("""Gets and prints the spreadsheet's header columns

Parameters
----------
file_loc : str
    The file location of the spreadsheet
print_cols : bool, optional
    A flag used to print the columns to the console (default is False)
    asjdfklasjdfkl

Returns
-------
list
    a list of strings representing the header columns
""")

class Param(text, can_be_unnamed=False, block_kind=None, **kw)

The Numpy parameter format.

{name} : {type}
    {description}