codertypist / mdgen

Automatically generate documentation/README for Python code. Simply fill in the blanks.

mdgen

Description

Automatically generate documentation written in Markdown for Python code. Simply fill in the blanks.

Motivation

Writing documentation sucks. This makes it easier. Often times people will choose to omit writing documentation since it is time consuming; however, documentation cannot be omitted in large scale projects. A lack of good documentation makes maintenance difficult and adoption less likely.

Documentation

Auto-generated by mdgen. Descriptions neeed to be manually completed.

_get_name()

def _get_name(line: str, num_omit: int) -> str:

Extract the function/class name from a line of code. Not meant to be used directly.

param	description
line: str	line of code
num_omit: int	number of characters to remove from the beginning of the line

returns: str:  function or class name

get_function_name()

def get_function_name(line: str) -> str:

Given a function declaration, extract the function name.

param	description
line: str	function declaration

returns: str:  function name

get_class_name()

def get_class_name(line: str) -> str:

Given a class declaration, extract the class name.

param	description
line: str	class declaration

returns: str:  class name

get_body()

def get_body(line: str):

In the case of a function, a list of function arguments is returned. In the case of a class, a list of classes that are being extended (inherited from) is returned.

param	description
line: str	line of code

returns: List:  List of function or arguments or list of classes the current class inherits from.

get_return_type()

def get_return_type(line: str) -> str:

Given a function declaration, extract the return type.

param	description
line: str	function declaration

returns: str:  return type

wprint()

def wprint(out_file, line: str, end='\n'):

In addition to printing the line to the console, the text is written out to a file if out_file is not None.

param	description
out_file	If not None, write the line out to the file.
line: str	line of code
end='\n'	append to the end of the line

returns: None

print_table()

def print_table(out, col_name: str, col_vals: List[str]) -> None:

Either prints a list of function of arguments or a list of class parents in table format.

param	description
out	If not None, write the table to the file (file should already be open)
col_name: str	Name of the first column which is used for col_vals
col_vals: List[str]	Values to place in the first column

returns: None

mdgen()

def mdgen(file_path: str, out: str=None):

Automatically generate documentation written in Markdown for Python code.

param	description
file_path: str	File containing Python code for which to generate documentation.
out: str=None	Write the Markdown out to this file.

returns: None