documentation: Update readme and puppetdoc documentation

Change-Id: I97ea6e3b4e7c4ac8b407dd3b6d39fd54ffae70fe

README.md

@@ -1,39 +1,85 @@
 puppet-designate
-======
+================
 
+#### Table of Contents
+
+1. [Overview - What is the designate module?](#overview)
+2. [Module Description - What does the module do?](#module-description)
+3. [Setup - The basics of getting started with designate](#setup)
+4. [Implementation - An under-the-hood peek at what the module is doing](#implementation)
+5. [Limitations - OS compatibility, etc.](#limitations)
+6. [Development - Guide for contributing to the module](#development)
+7. [Contributors - Those with commits](#contributors)
+8. [Release Notes - Notes on the most recent updates to the module](#release-notes)
+
+Overview
+--------
+
+The designate module is a part of [Stackforge](https://github.com/stackforge), an effort by the Openstack infrastructure team to provide continuous integration testing and code review for Openstack and Openstack community projects not part of the core software. The module itself is used to flexibly configure and manage the DNS service for Openstack.
 
 Module Description
 ------------------
 
-The designate module aims to make Puppet capable of managing the entirely of designate.
+Setup
+-----
 
+**What the designate module affects:**
+
+* designate, the DNS service for Openstack.
+
+Implementation
+--------------
+
+### designate
+
+designate is a combination of Puppet manifest and ruby code to delivery configuration and extra functionality through types and providers.
+
+Limitations
+-----------
+
+Development
+-----------
+
+Developer documentation for the entire puppet-openstack project.
+
+* https://wiki.openstack.org/wiki/Puppet-openstack#Developer_documentation
 
 WORK IN PROGRESS
 ----------------
 
-✓ Basic structure  
+✓ Basic structure
-✓ DB  
+✓ DB
-✓ Keystone (Users, Services, Endpoints)  
+✓ Keystone (Users, Services, Endpoints)
-✓ Client  
+✓ Client
-✓ designate-api  
+✓ designate-api
-✓ designate-central  
+✓ designate-central
-✗ designate-agent (in progress)  
+✗ designate-agent (in progress)
-✗ designate-sink  (in progress)  
+✗ designate-sink  (in progress)
-✓ An example of site.pp  
+✓ An example of site.pp
-✗ Write Tests (in progress)  
+✓ Write Tests
-
 
 Setup
 -----
 
 ### Get Prepared for Deployment
 
-    Currently there is no available RPM packages for use, you need to package it from source.
+#### Debian/Ubuntu
 
-    First, clone the spec file from   https://github.com/NewpTone/designate-spec.git
+* Debian testing (jessie) include all designate packages.
-    Then, clone the source file from  https://github.com/stackforge/designate.git
+* Ubuntu utopic is the minimum requirement for Ubuntu deployment.
-    Last, use rpmbuild to package it.
 
-### Installing Designate
+#### RedHat
+
+* Currently there is no available RPM packages for use, you need to package it from source.
+ * First, clone the spec file from   https://github.com/NewpTone/designate-spec.git
+ * Then, clone the source file from  https://github.com/stackforge/designate.git
+ * Last, use rpmbuild to package it.
+
+Contributors
+------------
+
+* https://github.com/stackforge/puppet-designate/graphs/contributors
+
+Release Notes
+-------------
 
-    You could ref the example file and install it.

manifests/agent.pp

@@ -1,5 +1,21 @@
-# Designate agent
+# == Class designate::agent
-
+#
+# Configure designate agent service
+#
+# == Parameters
+#
+# [*enabled*]
+#   (optional) Whether to enable services.
+#   Defaults to true
+#
+# [*service_ensure*]
+#  (optional) Whether the designate api service will be running.
+#  Defaults to 'running'
+#
+# [*backend_driver*]
+#  (optional) Driver used for backend communication (fake, rpc, bind9, powerdns)
+#  Defaults to 'bind9'
+#
 class designate::agent (
   $service_ensure = 'running',
   $backend_driver = 'bind9',

manifests/api.pp

@@ -1,5 +1,53 @@
-# class designate::api
+# == Class designate::api
-
+#
+# Configure designate API service
+#
+# == Parameters
+#
+# [*enabled*]
+#   (optional) Whether to enable services.
+#   Defaults to true
+#
+# [*service_ensure*]
+#  (optional) Whether the designate api service will be running.
+#  Defaults to 'running'
+#
+# [*auth_strategy*]
+#  (optional) Authentication strategy to use, can be either "noauth" or "keystone"
+#  Defaults to 'noauth'
+#
+# [*keystone_host*]
+#  (optional) Host running auth service.
+#  Defaults to '127.0.0.1'
+#
+# [*keystone_port*]
+#  (optional) Port to use for auth service on auth_host.
+#  Defaults to '35357'
+#
+# [*keystone_protocol*]
+#  (optional) Protocol to use for auth.
+#  Defaults to 'http'
+#
+# [*keystone_tenant*]
+#  (optional) Tenant to authenticate to.
+#  Defaults to 'services'
+#
+# [*keystone_user*]
+#  (optional) User to authenticate as with keystone.
+#  Defaults to 'designate'
+#
+# [*keystone_password*]
+#  (optional) Password used to authentication.
+#  Defaults to false
+#
+# [*enable_api_v1*]
+#  (optional) Enable Designate API Version 1
+#  Defaults to true
+#
+# [*enable_api_v2*]
+#  (optional) Enable Designate API Version 2 (experimental)
+#  Defaults to false
+#
 class designate::api (
   $enabled                    = true,
   $service_ensure             = 'running',

manifests/backend/bind9.pp

@@ -1,5 +1,25 @@
+# == Class designate::backend::bind9
+#
 # Configure bind9 as backend
-
+#
+# == Parameters
+#
+# [*rndc_config_file*]
+#   (optional) Location of the rndc configuration file.
+#   Defaults to '/etc/rndc.conf'
+#
+# [*rndc_key_file*]
+#  (optional) Location of the rndc key file.
+#  Defaults to '/etc/rndc.key'
+#
+# [*rndc_host*]
+#  (optional) Host running DNS service.
+#  Defaults to '127.0.0.1'
+#
+# [*rndc_port*]
+#  (optional) Port to use for dns service on rndc_host.
+#  Defaults to '953'
+#
 class designate::backend::bind9 (
   $rndc_host        = '127.0.0.1',
   $rndc_port        = '953',

manifests/central.pp

@@ -1,5 +1,21 @@
-# designate central service
+# == Class designate::central
-
+#
+# Configure designate central service
+#
+# == Parameters
+#
+# [*enabled*]
+#   (optional) Whether to enable services.
+#   Defaults to true
+#
+# [*service_ensure*]
+#  (optional) Whether the designate api service will be running.
+#  Defaults to 'running'
+#
+# [*backend_driver*]
+#  (optional) Driver used for backend communication (fake, rpc, bind9, powerdns)
+#  Defaults to 'bind9'
+#
 class designate::central (
   $service_ensure = 'running',
   $enabled        = true,

manifests/client.pp

@@ -1,9 +1,12 @@
+# == Class designate::client
 #
 # Installs the designate python library.
 #
-# == parameters
+# == Parameters
+#
 #  [*ensure*]
-#    ensure state for pachage.
+#    (optional) Ensure state for pachage.
+#    Defaults to 'present'
 #
 class designate::client (
   $ensure = 'present'

manifests/db.pp

@@ -1,8 +1,12 @@
+# == Class designate::db
+#
 # Configures the designate database
+#
 # This class will install the required libraries depending on the driver
 # specified in the connection_string parameter
 #
 # == Parameters
+#
 #  [*database_connection*]
 #    the connection string. format: [driver]://[user]:[password]@[host]/[database]
 #

manifests/dns.pp

@@ -1,5 +1,17 @@
+# == Class designate::dns
+#
 # Configure dns for designate service
-
+#
+# == Parameters
+#
+# [*designatepath*]
+#   (optional) Directory for maintaining designate's state
+#   Defailts to $designate::params::designatepath
+#
+# [*designatefile*]
+#   (optional) File for maintaining designate's state
+#   Defailts to $designate::params::designatefile
+#
 class designate::dns (
   $designatepath  = $::designate::params::designatepath,
   $designatefile  = $::designate::params::designatefile,

manifests/init.pp

@@ -1,5 +1,45 @@
-# Class designate
+# == Class designate
-
+#
+# Configure designate service
+#
+# == Parameters
+#
+# [*service_ensure*]
+#  (optional) Whether the designate-common package will be present..
+#  Defaults to 'present'
+#
+# [*debug*]
+#   (optional) should the daemons log debug messages.
+#   Defaults to 'false'
+#
+# [*verbose*]
+#   (optional) should the daemons log verbose messages.
+#   Defaults to 'false'
+#
+# [*root_helper*]
+#   (optional) Command for designate rootwrap helper.
+#   Defaults to 'sudo designate-rootwrap /etc/designate/rootwrap.conf'.
+#
+# [*rabbit_host*]
+#   (optional) Location of rabbitmq installation.
+#   Defaults to '127.0.0.1'
+#
+# [*rabbit_port*]
+#   (optional) Port for rabbitmq instance.
+#   Defaults to '5672'
+#
+# [*rabbit_password*]
+#   (optional) Password used to connect to rabbitmq.
+#   Defaults to 'guest'
+#
+# [*rabbit_userid*]
+#   (optional) User used to connect to rabbitmq.
+#   Defaults to 'guest'
+#
+# [*rabbit_virtualhost*]
+#   (optional) The RabbitMQ virtual host.
+#   Defaults to '/'
+#
 class designate(
   $package_ensure       = present,
   $verbose              = false,

manifests/sink.pp

@@ -1,5 +1,17 @@
-# Designate sink
+# == Class designate::sink
-
+#
+# Configure designate sink service
+#
+# == Parameters
+#
+# [*enabled*]
+#   (optional) Whether to enable services.
+#   Defaults to true
+#
+# [*service_ensure*]
+#  (optional) Whether the designate api service will be running.
+#  Defaults to 'running'
+#
 class designate::sink (
   $service_ensure = 'running',
   $enabled        = true,