Parsers

docstr_md.python.parsers.Sklearn

class docstr_md.python.parsers.Sklearn(raw_sections=('Notes', 'Examples')) [source]

Parses sklearn-style docstrings.

Parameters:	raw_sections : iterable of strings, default=('Notes','Examples') List of section names whose content will be treated as raw markdown. Other sections are treated as fields.
Attributes:	raw_sections : iterable of strings From raw_sections parameter.

Notes

'\' functions as an escape character when added to the beginning of a line. Whitespace to its left will be stripped. All text to its right will be treated as raw markdown.

Examples

from docstr_md.python import parsers

docstr_txt = '''
Description.

Field0
------
item0 : short description
    Long description.

item1 : short description
   Long description.

Field1
------
item0 : short description
   Long description

Notes
-----
Here is a note.

Examples
--------
Here is an example.
'''

parser = parsers.Sklearn()
parser(docstr_txt)

Out:

{
    'description': 'Description.',
    'sections': [
        ('Notes', 'Here is a note.'),
        ('Examples', 'Here is an example.')
    ],
    'fields': [
        {
            'name': 'Field0',
            'items': [
                {
                    'name': 'item0',
                    'short_desc': 'short description',
                    'long_desc': 'Long description.'
                },
                {
                    'name': 'item1',
                    'short_desc': 'short description',
                    'long_desc': 'Long description.'
                }
            ]
        },
        {
            'name': 'Field1',
            'items': [
                {
                    'name': 'item0',
                    'short_desc': 'short description',
                    'long_desc': 'Long description'
                }
            ]
        }
    ]
}

Methods

__call__(self, obj) [source]

Parses the docstring.

Parameters:	obj : str or docstr_md.python.soup_objects.Expr Raw docstring to be parsed.
Returns:	docstr : dict Parsed docstring dictionary. A dictionary contains a description (str), raw markdown sections (list), and fields (list). Each section is a (name, markdown) tuple. Each field contains a name (str) and items (list). Each item contains a name (str), a short description (usually the data type, str), and a long description (str).