eazydocs 24.9.26

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 looks to provide an easy way to generate code documentation by cutting down repetitive boilerplate input. 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.

eazydocs.generate_docs will scrape a Class object for functions and methods, then scrape the parameter names, types, and default arguments for each, returning a string expression formatted for a MD file. Passing a Function or Method object will do the same, instead only for the desired object. Optionally, you can create a MD file from the output, or append it to an existing file.

eazydocs.generate_example will format a pandas.DataFrames to include as an example in your README file. Optionally, you can append the example to an existing MD file, with the ability to specify the specific function or method you would like to insert the string expression under.

Table of Contents

• Installation
• eazydocs.generate_docs:
  • Overview
  • Using a Class object
  • Using a Method object
  • Creating a MD File
• eazydocs.generate_example:
  • Overview
  • Generating an Example
  • Appending to an Existing MD File

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-24.X.X-py3-none-any.whl
  

eazydocs.generate_docs

generate_docs(obj, append_to_file=False, skip_private=True, filename=_NoDefault.no_default, filepath=_NoDefault.no_default)

Parameters

• obj : object
  • A Class or Method object.
• append_to_file : bool, default False
  • Append the output string expression to a MD file.
• skip_private : bool, default True
  • Include functions or methods with the prefix '_' or '__'.
• filename : str, optional
  • String expression of the markdown file to append. Required argument if append_to_file=True.
• filepath : str, optional
  • String expression of the absolute path to the markdown file you are appending. If append_to_file=True, and filepath=None, the filename is expected to be in the current working directory.

Using a Class object

• This example generates documents for the object easydocs.Method:

  >>> from eazydocs import generate_docs
  
  >>> docs = generate_docs(Method)
  >>> print(docs)
  
  <strong id='method'>Method</strong>(<b>method_name</b>)
  
  > Parameters
  
  <ul style='list-style: none'>
      <li>
          <b>method_name : <i>str</i></b>
          <ul style='list-style: none'>
              <li>{description}</li>
          </ul>
      </li>
  </ul>
  

• The resulting MD file, when rendered:

  Method(method_name)
  
  

  Parameters

  • method_name : str
    • description

• Notice the placeholder generated under the method name: 'description'.

Using a Method object

• This example generates documents for the object eazydocs.generate_docs:

    >>> from eazydocs import generate_docs
  
    >>> docs = generate_docs(generate_docs)
    >>> print(docs)
  
    <strong id='generate-docs'>generate_docs</strong>(<b>obj</b>, <b>append_to_file</b><i>=False</i>, <b>filename</b><i>=_NoDefault.no_default</i>, <b>filepath</b><i>=_NoDefault.no_default</i>)
  
    > Parameters
  
    <ul style='list-style: none'>
        <li>
            <b>obj : <i>object</i></b>
            <ul style='list-style: none'>
                <li>description</li>
            </ul>
        </li>
        <li>
            <b>append_to_file : <i>bool, default False</i></b>
            <ul style='list-style: none'>
                <li>description</li>
            </ul>
        </li>
        <li>
            <b>filename : <i>str, optional</i></b>
            <ul style='list-style: none'>
                <li>description</li>
            </ul>
        </li>
        <li>
            <b>filepath : <i>str, optional</i></b>
            <ul style='list-style: none'>
                <li>description</li>
            </ul>
        </li>
    </ul>
  

• The resulting MD file when rendered:

  generate_docs(obj, append_to_file=False, filename=_NoDefault.no_default, filepath=_NoDefault.no_default)

  Parameters

  • obj : object
    • description
  • append_to_file : bool, default False
    • description
  • filename : str, optional
    • description
  • filepath : str, optional
    • description

Creating a MD file

• To create a MD file from generate_docs output, you can set its append_to_file to True. This will create a README.md file in your current working directory:

  >>> from eazydocs import generate_docs
  
  >>> generate_docs(Method, append_to_file=True)
  

• However, you may want to append the documents to an existing MD file, in which case you can provide the filename:

  >>> from eazydocs import generate_docs
  
  >>> generate_docs(
        Method,
        append_to_file=True,
        filename='METHOD'
      )
  

• Optionally, you can provide a filepath to the MD file, in addition to the filename:

  >>> from eazydocs import generate_docs
  
  >>> generate_docs(
        Method,
        append_to_file=True,
        filename='METHOD',
        filepath='~/$USER/eazydocs/output'
      )
  

  • The string argument provided to filepath is joined with filename as a pathlib.Path object

eazydocs.generate_example

generate_example(df, df_shape=[5, 5], code='df', append_to_file=False, filename=_NoDefault.no_default, filepath=_NoDefault.no_default, method_name=_NoDefault.no_default)

Parameters

• df : pandas.DataFrame
  • Pandas DataFrame to format.
• df_shape : list[int], default [5, 5]
  • Integer list defining the desired shape of the df. First integer is the desired number of rows, while the second is the desired number of columns. Passing df_shape=[-1, -1] will generate the string expression without reshaping df - not recommended for large DataFrames.
• code : str, default 'df'
  • Line of code you would like displayed before the DataFrame example. This is useful if you are demonstrating how a method changes a DataFrame.
• append_to_file : bool, default False
  • Append output string expression to an existing MD file.
• filename : str, optional
  • String expression of the markdown file to append. Required argument if append_to_file=True.
• filepath : str, optional
  • String expression of the absolute path to the markdown file you are appending. If append_to_file=True, and filepath=None, the MD file is expected to be in the current working directory.
• method_name : str, optional
  • String expression of the specific method name you would like to insert this example under. If method_name=None, the string generated from the example is inserted at the end of the MD file.

Creating an Example from a pandas.DataFrame

• Basic example using default parameters:

  >>> from eazydocs import generate_example
  >>> df = DataFrame({'col_1': [0, 1, 2, 3, 4, 5], 'col_2': [0, 1, 2, 3, 4, 5], 'col_3': [0, 1, 2, 3, 4, 5] ... 'col_10': [0, 1, 2, 3, 4, 5]})
  >>> df.shape
      (7, 10)
  
  >>> example = generate_example(df)
  >>> example
      ```
      >>> df
      col_1  col_2  col_3  col_4  col_5
      0      0      0      0      0      0
      1      1      1      1      1      1
      2      2      2      2      2      2
      3      3      3      3      3      3
      4      4      4      4      4      4
      ```
  

• Specifying the shape of the DataFrame before its formatted to a string expression:

      >>> df = DataFrame({'col_1': [0, 1, 2, 3, 4, 5], 'col_2': [0, 1, 2, 3, 4, 5], 'col_3': [0, 1, 2, 3, 4, 5] ... 'col_10': [0, 1, 2, 3, 4, 5]})
      >>> df.shape
          (7, 10)
  
      >>> example = generate_example(df, df_shape=(5,10))
      >>> example
          ```
          >>> df
          col_1  col_2  col_3  col_4  col_5
          0      0      0      0      0      0
          1      1      1      1      1      1
          2      2      2      2      2      2
          3      3      3      3      3      3
          4      4      4      4      4      4
          ```
  

• Specifying the code displayed before the string expression:

  >>> dff = DataFrame({'col_1': [0, 1, 2, 3, 4, 5], 'col_2': [0, 1, 2, 3, 4, 5], 'col_3': [0, 1, 2, 3, 4, 5] ... 'col_10': [0, 1, 2, 3, 4, 5]})
  
  >>> example = generate_example(dff, code = 'dff')
  >>> example
      ```
      >>> dff
      col_1  col_2  col_3  col_4  col_5
      0      0      0      0      0      0
      1      1      1      1      1      1
      2      2      2      2      2      2
      3      3      3      3      3      3
      4      4      4      4      4      4
      ```
  

Appending the example to an existing MD file:

>>> generate_example(df, append_to_file=True, filename='EXAMPLE')
Succesfully updated 'EXAMPLE.md' (~/$USER/easydocs/EXAMPLE.md)

• Appending the example to a method in an existing MD file:

  • Note: This requires the existing MD file to have been created, or at least the desired method, using eazydocs.generate_docs().

    cls.py

    class Cls:
        def __init__(self, s1: str) -> None:
            ...
    
        def method_1(self, new_str: str) -> str:
            ...
    
        def method_2(self, another_str: str, optional_str: str) -> str:
            ...
    

    ~/$USER/README.md

    Cls(s1)

    Parameters

    • s1 : str
      • description

    method_1(new_str)

    Parameters

    • new_str : str
      • description

    method_2(another_str, optional_str)

    Parameters

    • another_str : str
      • description
    • optional_str : str
      • description

    
    

    ~/$USER/main.py

    ```
    >>> df = DataFrame({'col_1': [0, 1, 2, 3, 4, 5], 'col_2': [0, 1, 2, 3, 4, 5], 'col_3': [0, 1, 2, 3, 4, 5] ... 'col_10': [0, 1, 2, 3, 4, 5]})
    
    >>> generate_example(df, df_shape=(5,10), append_to_file=True, filename='README', method_name='method_1')
    Successfully update 'method_1' in 'README.md' (~/$USER/README.md)
    ```
    

    ~/$USER/README.md

    Cls(s1)

    Parameters

    • s1 : str
      • description

    method_1(new_str)

    Parameters

    • new_str : str
      • description

    Example

    >>> df
    col_1  col_2  col_3  col_4  col_5
    0      0      0      0      0      0
    1      1      1      1      1      1
    2      2      2      2      2      2
    3      3      3      3      3      3
    4      4      4      4      4      4
    

    method_2(another_str, optional_str)

    Parameters

    • another_str : str
      • description
    • optional_str : str
      • description