fix #22: clean up code docs and use pymdgen for api docs

CHANGELOG.md

@@ -8,6 +8,9 @@
 
 ### Fixed
 ### Changed
+
+- use pymdgen for automatic api docs (#22)
+
 ### Deprecated
 ### Removed
 ### Security

Ctl/requirements-docs.txt

@@ -1,2 +1,3 @@
-markdown-include==0.5.1
+markdown-include>=0.5,<1
 mkdocs>=1.0.0,<2.0.0
+pymdgen<2

confu/cli.py

@@ -1,16 +1,44 @@
+"""
+functions that allow you to generate CLI parameters from a confu schema for
+argparse or click
+"""
+
 try:
     import click
 except ImportError:
     pass
 
 
 def option_name(path, delimiter="--"):
-    """returns a cli option name from attribute path"""
+    """
+    Returns a cli option name from attribute path
+
+    **Arguments**
+
+    - path (`list`): attribute path
+    - delimiter (`str`): delimiter for nested attributes
+
+    **Returns**
+
+    cli option name (`str`)
+    """
+
     return "--{}".format(delimiter.join(path).replace("_", "-"))
 
 
 def destination_name(path, delimiter="__"):
-    """returns a cli option destination name from attribute path"""
+    """
+    Returns a cli option destination name from attribute path
+
+    **Arguments**
+
+    - path (`list`): attribute path
+    - delimiter (`str`): delimiter for nested attributes
+
+    **Returns**
+
+    cli destination name (`str`)
+    """
     return "{}".format(delimiter.join(path))
 
 
@@ -26,6 +54,22 @@ def default(value, path, defaults):
 
 
 def argparse_options(parser, schema, defaults=None, attributes=None):
+
+    """
+    Add cli options to an argparse ArgumentParser instance
+
+    **Arguments**
+
+    - parser (`argparse.ArgumentParser`)
+    - schema (`Schema`)
+
+    **Keyword Arguments**
+
+    - defaults (`dict`): if specified will override defaults from here
+    - attributes (`list<str>`): can hold a list of attribute names.
+    if specified only matching attributes will be aded
+    """
+
     def optionize(attribute, path):
         if not attribute.cli:
             return
@@ -55,6 +99,23 @@ def optionize(attribute, path):
 
 
 class click_options(object):
+
+    """
+    Add cli options to a click decorated function
+
+    Use like a decorator
+
+    **Arguments**
+
+    - schema (`Schema`)
+
+    **Keyword Arguments**
+
+    - defaults (`dict`): if specified will override defaults from here
+    - attributes (`list<str>`): can hold a list of attribute names.
+    if specified only matching attributes will be aded
+    """
+
     def __init__(self, schema, defaults=None, attributes=None):
         self.schema = schema
         self.defaults = defaults

confu/config.py

@@ -1,3 +1,6 @@
+"""
+config management
+"""
 from __future__ import absolute_import, division, print_function
 
 import collections
@@ -13,9 +16,14 @@ class for storing and manipulating config data
 
     def __init__(self, schema, data=None, meta=None):
         """
-        `schema` confu.schema object
-        `data` dict to set initial data
-        `meta` any addition metadata to pass along with config
+        **Arguments**
+
+        - schema (`confu.schema`): schema object
+
+        **Keyword Arguments**
+
+        - data (`dict`): dict to set initial data
+        - meta (`dict`): any additional metadata to pass along with config
         """
         self._base_data = None
         self._data = None

confu/exceptions.py

@@ -1,12 +1,29 @@
 class SoftDependencyError(ImportError):
+    """
+    Raised when a feature requires a dependency that is missing
+    """
+
     def __init__(self, dep_name):
         super(SoftDependencyError, self).__init__(
             "To use this feature this dependency is required: {}".format(dep_name)
         )
 
 
 class ValidationErrorBase(ValueError):
+    """
+    Config validation error interface
+    """
+
     def __init__(self, attribute, path, value, reason):
+        """
+        **Arguments**
+
+        - attribute (`Attribute`): confu attribute instance
+        - path (`list`): attribute path
+        - value (`mixed`): value that caused the validation error
+        - reason (`str`): human readable reason message for validation error
+        """
+
         msg = "{}: {}".format(path, reason)
         self.details = {
             "path": path,
@@ -18,6 +35,9 @@ def __init__(self, attribute, path, value, reason):
 
     @property
     def pretty(self):
+        """
+        pretty formatted error message
+        """
         return "{}: {}".format(
             ".".join([str(i) for i in self.details["path"]]), self.details["reason"]
         )
@@ -34,13 +54,25 @@ def __eq__(self, other):
 
 
 class ValidationWarning(ValidationErrorBase):
+    """
+    Config validation warning
+    """
+
     pass
 
 
 class ValidationError(ValidationErrorBase):
+    """
+    Config validation error
+    """
+
     pass
 
 
 class ApplyDefaultError(ValidationErrorBase):
+    """
+    Raised when an exception occured during apply_defaults
+    """
+
     def __str__(self):
         return self.pretty

confu/generator.py

@@ -1,11 +1,31 @@
+"""
+Schema to data generators
+"""
 from confu.schema import Schema, Attribute
 
 
 class ConfigGenerator(object):
+    """
+    Generate config from schema using default values
+    """
+
     def __init__(self):
         pass
 
     def generate(self, schema):
+
+        """
+        Generate confug from schema using default values
+
+        **Arguments**
+
+        - schema (`Schema|Attribute`): confu schema object
+
+        **Returns**
+
+        generated config `dict`
+        """
+
         if isinstance(schema, Schema):
             config = {}
             for name, attribute in schema.attributes():
@@ -21,6 +41,19 @@ def generate(self, schema):
 def generate(schema, generator=None):
     """
     generate config shortcut function
+
+    **Arguments**
+
+    - schema (`Schema`): confu schema object
+
+    **Keyword Arguments**
+
+    - generator (`ConfigGenerator`): generator object, if non is supplied
+    will instantiate a ConfigGenerator instance itself
+
+    **Returns**
+
+    generated config (`dict`)
     """
     if not generator:
         generator = ConfigGenerator()