Skip to main content

Automatic style guide and docstrings generator for Python code

Project description

alphadoc

PyPI version ISSUES PULL REQUESTS

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.
  • Automatically fixes the code according to the standard PEP-8 style convention for python.
  • Support for common and widely used docstrings formats such as Numpy, Google, ReStructured Text and Epytext (Javadoc)

Installation

Using pip:

$ pip install alphadoc

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

alphadoc-1.0.3.tar.gz (5.1 kB view details)

Uploaded Source

Built Distributions

alphadoc-1.0.3-py3.6.egg (11.8 kB view details)

Uploaded Source

alphadoc-1.0.3-py3-none-any.whl (7.4 kB view details)

Uploaded Python 3

File details

Details for the file alphadoc-1.0.3.tar.gz.

File metadata

  • Download URL: alphadoc-1.0.3.tar.gz
  • Upload date:
  • Size: 5.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.0 setuptools/50.3.2 requests-toolbelt/0.9.1 tqdm/4.53.0 CPython/3.6.9

File hashes

Hashes for alphadoc-1.0.3.tar.gz
Algorithm Hash digest
SHA256 60b1cce58c454b017f74fd4b3227e15cbd321d51d6c1f7fce34401b7e492ffc7
MD5 72f6ee475b0a3f588c48ffcaf4cda00e
BLAKE2b-256 1394c662e76208c4cfbccc2d84af75d466c6e4cac222c589ca44cb80b22747b3

See more details on using hashes here.

File details

Details for the file alphadoc-1.0.3-py3.6.egg.

File metadata

  • Download URL: alphadoc-1.0.3-py3.6.egg
  • Upload date:
  • Size: 11.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.0 setuptools/50.3.2 requests-toolbelt/0.9.1 tqdm/4.53.0 CPython/3.6.9

File hashes

Hashes for alphadoc-1.0.3-py3.6.egg
Algorithm Hash digest
SHA256 5380a2b703016fe3041d4c9fdd78433761053db08a5ceb5a4b324c1cff6dbe56
MD5 aa69bc636226f42ab4dca80cb2823f8e
BLAKE2b-256 41a97b91e5a2fecbe4879a6d32a800ee3b579eb5c12186e1d93f606a8602ade6

See more details on using hashes here.

File details

Details for the file alphadoc-1.0.3-py3-none-any.whl.

File metadata

  • Download URL: alphadoc-1.0.3-py3-none-any.whl
  • Upload date:
  • Size: 7.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.0 setuptools/50.3.2 requests-toolbelt/0.9.1 tqdm/4.53.0 CPython/3.6.9

File hashes

Hashes for alphadoc-1.0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 32e0bb5f8daaafbf1d063db89b53994db4011ce350fa50631f74d2ce1e8fc4de
MD5 a2c721e0c897d7d3f11478f9c9481e70
BLAKE2b-256 f8a4fb15283165c4293c1f94ac9511ab9088114e66b261c3dc10425d0a2d5720

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page