eazydocs 25.6.0

An easy way to generate code documentation by cutting down repetitive boilerplate input. With as little as the function name and its parameters, you can generate a markdown file that mixes markdown and html formatting to clearly define your code.

EazyDocs

EazyDocs provides a simple way to generate documentation for Python classes and methods. By providing a class or method object, you can generate a markdown (MD) file that mixes markdown and html formatting to clearly define your code.

Table of Contents

• Installation
• Methods
  • get_documentation
  • create_md_file
  • update_md_file
  • get_example

Installation

• Install the eazydocs module using your preferred package manager:z

  pip install eazydocs
  

• Alternatively, the .whl can be downloaded and installed:

  pip install eazydocs-X.X.X-py3-none-any.whl
  

Methods

get_documentation(class_or_method=None, include_methods=True, include_private_methods=False, include_examples=True, to_clipboard=True)

Generate documentation for a class or method.

Parameters:

• class_or_method : object | FunctionType | MethodType, None
  • The class or method to generate documentation for.
• include_methods : bool, optional, True
  • Whether to include methods in the documentation. Defaults to True.
• include_private_methods : bool, optional, False
  • Whether to include private methods in the documentation. Defaults to False.
• include_examples : bool, optional, True
  • Whether to include examples in the documentation. Defaults to True.
• to_clipboard : bool, optional, True
  • If True, the output will be copied to the clipboard. Defaults to True.

Examples:

Basic Usage with a Class:

from eazydocs import get_documentation

>>> get_documentation(ExampleClass)
Successfully copied to clipboard!

• Output for ExampleClass will contain the documentation for the class and its methods.
• Using include_methods=False will exclude methods from the output.
• Using include_private_methods=True will include private methods in the output.
• Using include_examples=False will exclude examples from the output.
• Using to_clipboard=False will allow you to print the output to the console instead of copying it to the clipboard.

Basic Usage with a Method:

from eazydocs import get_documentation

>>> get_documentation(ExampleClass.example_method)
Successfully copied to clipboard!

• Output for ExampleClass.example_method will contain the documentation for the method only.

---

create_md_file(class_or_method=None, filename="README.md", path=None, overwrite=False)

Generate a markdown file for a class or method.

Parameters:

• class_or_method : ClassMethodType, None
  • Class or method to generate documentation for.
• filename : StrPathType, optional, "README.md"
  • String or Path object for the filename. If a string object is provided, the file will be saved to the current working directory. Defaults to "README.md".
• path : StrPathType, optional, None
  • Directory path where the file will be saved. If not provided, the file will be saved in the current working directory. If provided, the filename will be joined to path argument. Defaults to None.
• overwrite : bool, optional, False
  • If True, the existing file will be overwritten without confirmation. Defaults to False.

Examples:

Basic Usage:

from eazydocs import create_md_file

>>> create_md_file(ExampleClass)
Successfully created markdown file: 'README.md'

• File is created in the current working directory with the name "README.md".

Specifying a filename and path:

from eazydocs import create_md_file

>>> create_md_file(ExampleClass, filename="ExampleClass.md", path="./docs")
Successfully created markdown file: './docs/ExampleClass.md'

---

update_md_file(class_or_method=None, filename=None, path=None)

Update an EazyDocs generated markdown file. If a class is provided, it will overwrite the provided file. Otherwise, it will trim the old method documentation from the file, insert the updated documentation, and write it to the given filename.

Parameters:

• class_or_method : ClassMethodType, None
  • Class or method to update.
• filename : StrPathType, None
  • String or Path object representing the markdown file to update.
• path : StrPathType, optional, None
  • String or Path object for the path where the file will be saved. If not provided, the file will be saved in the current working directory. If provided, the filename will be joined to path argument. Defaults to None.

Notes:

• The markdown file must have been generated by EazyDocs for the update to work.
• Updating a class will overwrite the entire file.

Examples: Basic Usage with a Class:

from eazydocs import update_md_file

>>> update_md_file(ExampleClass, filename="README.md")
Successfully updated markdown file: 'README.md'

• Since a class is provided, the entire file will be overwritten with the new documentation.

Basic Usage with a Method:

from eazydocs import update_md_file

>>> update_md_file(ExampleClass.example_method, filename="README.md")
Successfully updated markdown file: 'README.md'

• Since a method is provided, only the documentation for that method will be updated in the file.

---

get_example(arg=None, df_shape=None, copy_to_clipboard=True, append_to_method=None, filename=None, path=None)

Generate an example representation of a DataFrame or method.

Parameters:

• arg : DataFrame | FunctionMethodType, None
  • The DataFrame or method to generate an example for.
• df_shape : tuple[int,int] | DfShape, optional, None
  • A tuple or DfShape specifying the number of rows and columns to display from the DataFrame. If type(arg)==DataFrame and df_shape=None, the default shape of (5,5) will be used. Defaults to None.
• copy_to_clipboard : bool, optional, True
  • If True, the output will be copied to the clipboard. Defaults to True.
• append_to_method : str, optional, None
  • If provided, the example will be appended to the specified method in the markdown file. If append_to_method!=None, filename must also be provided. Optionally providing the path argument. Defaults to None.
• filename : StrPathType, optional, None
  • String or Path object for the filename. Defaults to None.
• path : StrPathType, optional, None
  • Directory path where the file will be located. Defaults to None.

Examples:

Basic Usage with a DataFrame:

import pandas as pd
from eazydocs import get_example

>>> df = pd.DataFrame({
...     "A": range(1, 11),
...     "B": range(11, 21),
})
>>> get_example(df, df_shape=(3, 2))
Successfully copied to clipboard!

• Output will be a markdown table representation of the DataFrame with 3 rows and 2 columns:

  |   A |   B |
  | --: | --: |
  |   1 |  11 |
  |   2 |  12 |
  |   3 |  13 |
  

Basic Usage with a Method:

from eazydocs import get_example

>>> def example_method(x):
...     return x * 2
>>> get_example(example_method)
Successfully copied to clipboard!

• Output will be a code block boilerplate for the method:

  example_method()
  

---