alphadoc

Automatic docstring generator and style guide that supports a number of specified conventions for documentation in Python.

Features

• Auto-generates docstrings with a customizable template for functions.
• Support for common and widely used docstrings formats such as Numpy, Google, ReStructured Text and Epytext (Javadoc)

Installation

Using pip:

$ pip install alphadoc

Demo

Usage

alphadoc takes your filename and format type as arguments

$ alphadoc <filename> -d <doc_format>

See alphadoc --help for more command-line switches and options!

Options :

Usage: alphadoc [OPTIONS] FILENAME

  Automatic docstring generator and style guide that  supports a
  number of specified conventions for formatting  as well as
  documentation in Python.

Options:
  -d, --doc_format TEXT  Specified format for docstrings from Options-
                         ReST : For ReStructured Text (default); Epytext
                         :  For Epytext (Javadoc); Google : For Google-
                         Style ; Numpydoc : For Numpydoc

  --help                 Show this message and exit.

Example :

Before alphadoc

import ast
import sys

def top_level_functions(body):
    return (f for f in body if isinstance(f, ast.FunctionDef))

def parse_ast(filename):
    with open(filename, "rt") as file:
        return ast.parse(file.read(), filename=filename)

def get_func(filename):
    tree = parse_ast(filename)
    func_list = []
    for func in top_level_functions(tree.body):
        func_list.append(func.name)
    return func_list

After alphadoc

Docstring format:

• ReStructured Text (default)

import ast
import sys

def top_level_functions(body):
    """
        This is reST style.

        :param param1: this is a first param
        :param param2: this is a second param
        :returns: this is a description of what is returned
        :raises keyError: raises an exception
    """
    return (f for f in body if isinstance(f, ast.FunctionDef))

def parse_ast(filename):
    """
        This is reST style.

        :param param1: this is a first param
        :param param2: this is a second param
        :returns: this is a description of what is returned
        :raises keyError: raises an exception
    """
    with open(filename, "rt") as file:
        return ast.parse(file.read(), filename=filename)

def get_func(filename):
    """
        This is reST style.

        :param param1: this is a first param
        :param param2: this is a second param
        :returns: this is a description of what is returned
        :raises keyError: raises an exception
    """
    tree = parse_ast(filename)
    func_list = []
    for func in top_level_functions(tree.body):
        func_list.append(func.name)
    return func_list

• Epytext (Javadoc)

import ast
import sys

def top_level_functions(body):
    """
        This is javadoc style.

        @param param1: this is a first param
        @param param2: this is a second param
        @return: this is a description of what is returned
        @raise keyError: raises an exception
    """
    return (f for f in body if isinstance(f, ast.FunctionDef))

def parse_ast(filename):
    """
        This is javadoc style.

        @param param1: this is a first param
        @param param2: this is a second param
        @return: this is a description of what is returned
        @raise keyError: raises an exception
    """
    with open(filename, "rt") as file:
        return ast.parse(file.read(), filename=filename)

def get_func(filename):
    """
        This is javadoc style.

        @param param1: this is a first param
        @param param2: this is a second param
        @return: this is a description of what is returned
        @raise keyError: raises an exception
    """
    tree = parse_ast(filename)
    func_list = []
    for func in top_level_functions(tree.body):
        func_list.append(func.name)
    return func_list

• Google

import ast
import sys

def top_level_functions(body):
    """
            This is an example of Google style.
            
            Args:
            param1: This is the first param.
            param2: This is a second param.

            Returns:
            This is a description of what is returned.

            Raises:
            KeyError: Raises an exception.
    """
    return (f for f in body if isinstance(f, ast.FunctionDef))

def parse_ast(filename):
    """
            This is an example of Google style.
            
            Args:
            param1: This is the first param.
            param2: This is a second param.

            Returns:
            This is a description of what is returned.

            Raises:
            KeyError: Raises an exception.
    """
    with open(filename, "rt") as file:
        return ast.parse(file.read(), filename=filename)

def get_func(filename):
    """
            This is an example of Google style.
            
            Args:
            param1: This is the first param.
            param2: This is a second param.

            Returns:
            This is a description of what is returned.

            Raises:
            KeyError: Raises an exception.
    """
    tree = parse_ast(filename)
    func_list = []
    for func in top_level_functions(tree.body):
        func_list.append(func.name)
    return func_list

• Numpydoc

import ast
import sys

def top_level_functions(body):
    """
        Numpydoc description of a kind
        of very exhautive numpydoc format docstring.

        Parameters
        ----------
        first : array_like
            the 1st param name `first`
        second :
            the 2nd param
        third : {'value', 'other'}, optional
            the 3rd param, by default 'value'

        Returns
        -------
        string
            a value in a string

        Raises
        ------
        KeyError
            when a key error
        OtherError
            when an other error
    """
    return (f for f in body if isinstance(f, ast.FunctionDef))

def parse_ast(filename):
    """
        Numpydoc description of a kind
        of very exhautive numpydoc format docstring.

        Parameters
        ----------
        first : array_like
            the 1st param name `first`
        second :
            the 2nd param
        third : {'value', 'other'}, optional
            the 3rd param, by default 'value'

        Returns
        -------
        string
            a value in a string

        Raises
        ------
        KeyError
            when a key error
        OtherError
            when an other error
    """
    with open(filename, "rt") as file:
        return ast.parse(file.read(), filename=filename)

def get_func(filename):
    """
        Numpydoc description of a kind
        of very exhautive numpydoc format docstring.

        Parameters
        ----------
        first : array_like
            the 1st param name `first`
        second :
            the 2nd param
        third : {'value', 'other'}, optional
            the 3rd param, by default 'value'

        Returns
        -------
        string
            a value in a string

        Raises
        ------
        KeyError
            when a key error
        OtherError
            when an other error
    """
    tree = parse_ast(filename)
    func_list = []
    for func in top_level_functions(tree.body):
        func_list.append(func.name)
    return func_list

References

http://daouzli.com/blog/docstring.html

Contributing

alphadoc is fully Open-Source and open for contributions! We request you to respect our contribution guidelines as defined in our CODE_OF_CONDUCT.md and CONTRIBUTING.md

Contributors