Basic Use

docstr_md.python.PySoup

class docstr_md.python.PySoup(code=None, path='', parser='sklearn', src_href=None) [source]

This class parses raw Python code for easy conversion to markdown.

Parameters:

code : str, default=None Raw Python code. path : str, default='' Path to python file. One of code or path must be specified. parser : callable or str, default='sklearn' If input as a string, PySoup uses it as a key to look up a built-in parser. The parser takes a raw docstring and returns a docstr dictionary.

Attributes:

objects : list List of soup objects; expressions (Expr), functions (FunctionDef), classes (ClassDef) or string. Strings are usually interpreted as raw markdown. parser : callable The input parser. import_path : str Import path for soup objects. Setting the import path for the soup automatically sets the import path for its objects. src_path : str Path to the file in the source code repository (e.g. Github). Setting the source code path for the soup automatically sets the source code path for its objects. src_href : callable The src_href takes a soup object (FunctionDef or ClassDef) and converts it to a link to the source code. Setting the src_href for the soup automatically sets the src_href attribute for its objects.

Examples

Create a python file with parseable docstrings.

from docstr_md.python import PySoup

# replace with the appropriate file path and docstring parser
soup = PySoup(path='path/to/file.py', parser='sklearn')

Methods

convert_ast_object(self, obj) [source]

Convert an ast object to a soup object.

Parameters:	obj : ast.Expr, ast.FunctionDef, or ast.ClassDef ast object to convert.
Returns:	soup_object : Expr, FunctionDef, or ClassDef Specified in docstr_md/python/soup_objects.py.

rm_properties(self) [source]

Remove methods with getter, setter, and deleter decorators from all ClassDef soup objects in the objects list.

Returns:	self : docstr_md.python.PySoup

Examples

Create a python file with a class with methods decorated with @property, @x.setter, or @x.deleter.

from docstr_md.python import PySoup

soup = PySoup(path='path/to/file.py', parser='sklearn')
soup.rm_properties()

The ClassDef soup objects' methods will no longer include properties.

rm_objects(self, *names) [source]

Remove objects by name.

Parameters:	*names : str Object names to remove.
Returns:	self : docstr_md.python.PySoup

keep_objects(self, *names, keep_expr=True) [source]

Keep objects by name.

Parameters:	*names : str Object names to keep. keep_expr : bool, default=True Indicates that expressions (which don't have names) should be kept.
Returns:	self : docstr_md.python.PySoup

docstr_md.python.compile_md

def docstr_md.python.compile_md(soup, compiler='sklearn', outfile=None) [source]

Compile markdown from a PySoup object.

Parameters:	soup : PySoup Soup object to convert to markdown. compiler : callable or str, default='sklearn' If input as a string, it compiler is used as a key to look up a built-in compiler. The compiler takes the soup and returns a string in markdown format. outfile : str or None File to which to write the markdown.
Returns:	markdown : str Markdown formatted as output by the compiler.

Examples

Create a python file with parseable docstrings.

from docstr_md.python import PySoup, compile_md

# replace with the appropriate file path and parser
soup = PySoup(path='path/to/file.py', parser='sklearn')
# replace with your desired compiler and output file path
compile_md(soup, compiler='sklearn', outfile='path/to/outfile.md')

You can find the compiled markdown file in test.md.