hvac · jeffwecan · Jul 14, 2018 · Jul 14, 2018 · Jul 14, 2018 · Jul 14, 2018
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,6 @@
 *~
 
 /hvac/version
+
+# sphinx build folder
+docs/_build/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.6.2 (UNRELEASED)
+
+IMPROVEMENTS:
+
+* sphinx documentation and [readthedocs.io project](https://hvac.readthedocs.io/en/latest/) added. [GH-222]
+* README.md included in setuptools metadata. [GH-222]
+* All `tune_secret_backend()` parameters now accepted. [GH-215]
+
+Thanks to @bbayszczak for their lovely contributions.
+
 ## 0.6.1 (July 5th, 2018)
 
 IMPROVEMENTS:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,18 @@
+# Contributing
+
+Feel free to open pull requests with additional features or improvements!
+
+## Testing
+
+Integration tests will automatically start a Vault server in the background. Just make sure
+the latest `vault` binary is available in your `PATH`.
+
+1. [Install Vault](https://vaultproject.io/docs/install/index.html) or execute `VAULT_BRANCH=release scripts/install-vault-release.sh`
+2. [Install Tox](http://tox.readthedocs.org/en/latest/install.html)
+3. Run tests: `make test`
+
+## Documentation
+
+### Examples
+
+Example code or general guides for methods in this module can be added under [docs/examples](docs/examples).
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
-# HVAC
+# hvac
 
 [HashiCorp](https://hashicorp.com/) [Vault](https://www.vaultproject.io) API client for Python 2/3
 
-[![Travis CI](https://travis-ci.org/ianunruh/hvac.svg?branch=master)](https://travis-ci.org/ianunruh/hvac) [![Latest Version](https://img.shields.io/pypi/v/hvac.svg)](https://pypi.python.org/pypi/hvac/)
+[![Travis CI](https://travis-ci.org/ianunruh/hvac.svg?branch=master)](https://travis-ci.org/ianunruh/hvac) [![Latest Version](https://img.shields.io/pypi/v/hvac.svg)](https://pypi.python.org/pypi/hvac/) [![Documentation Status](https://readthedocs.org/projects/hvac/badge/)](https://hvac.readthedocs.io/en/latest/?badge=latest)
 
 Tested against Vault v0.1.2 and HEAD. Requires v0.1.2 or later.
 
@@ -35,11 +35,8 @@ client = hvac.Client(url='http://localhost:8200', token=os.environ['VAULT_TOKEN'
 client = hvac.Client(url='https://localhost:8200')
 
 # Using TLS with client-side certificate authentication
-client = hvac.Client(url='https://localhost:8200',
-                     cert=('path/to/cert.pem', 'path/to/key.pem'))
+client = hvac.Client(url='https://localhost:8200', cert=('path/to/cert.pem', 'path/to/key.pem'))
 
- # Skipping TLS verification entirely (should only be used for local development; unsafe for production clusters)
- client = hvac.Client(url='https://localhost:8200', verify=False)
 ```
 
 ### Read and write to secret backends
@@ -52,218 +49,10 @@ print(client.read('secret/foo'))
 client.delete('secret/foo')
 ```
 
-### Authenticate to different auth backends
+### Authenticate using token auth backend
 
 ```python
 # Token
 client.token = 'MY_TOKEN'
 assert client.is_authenticated() # => True
-
-# App ID
-client.auth_app_id('MY_APP_ID', 'MY_USER_ID')
-
-# App Role
-client.auth_approle('MY_ROLE_ID', 'MY_SECRET_ID')
-
-# AWS (IAM)
-client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY')
-client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY', 'MY_AWS_SESSION_TOKEN')
-client.auth_aws_iam('MY_AWS_ACCESS_KEY_ID', 'MY_AWS_SECRET_ACCESS_KEY', role='MY_ROLE')
-
-import boto3
-session = boto3.Session()
-credentials = session.get_credentials()
-client.auth_aws_iam(credentials.access_key, credentials.secret_key, credentials.token)
-
-# GitHub
-client.auth_github('MY_GITHUB_TOKEN')
-
-# GCP (from GCE instance)
-import requests
-
-VAULT_ADDR="https://vault.example.com:8200"
-ROLE="example"
-AUDIENCE_URL =  VAULT_ADDR + "/vault/" + ROLE
-METADATA_HEADERS = {'Metadata-Flavor': 'Google'}
-FORMAT = 'full'
-
-url = 'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience={}&format={}'.format(AUDIENCE_URL, FORMAT)
-r = requests.get(url, headers=METADATA_HEADERS)
-client.auth_gcp(ROLE, r.text)
-
-# Kubernetes (from k8s pod)
-f = open('/var/run/secrets/kubernetes.io/serviceaccount/token')
-jwt = f.read()
-client.auth_kubernetes("example", jwt)
-
-# LDAP, Username & Password
-client.auth_ldap('MY_USERNAME', 'MY_PASSWORD')
-client.auth_userpass('MY_USERNAME', 'MY_PASSWORD')
-
-# TLS
-client = Client(cert=('path/to/cert.pem', 'path/to/key.pem'))
-client.auth_tls()
-
-# Non-default mount point (available on all auth types)
-client.auth_userpass('MY_USERNAME', 'MY_PASSWORD', mount_point='CUSTOM_MOUNT_POINT')
-
-# Authenticating without changing to new token (available on all auth types)
-result = client.auth_github('MY_GITHUB_TOKEN', use_token=False)
-print(result['auth']['client_token']) # => u'NEW_TOKEN'
-
-# Custom or unsupported auth type
-params = {
-    'username': 'MY_USERNAME',
-    'password': 'MY_PASSWORD',
-    'custom_param': 'MY_CUSTOM_PARAM',
-}
-
-result = client.auth('/v1/auth/CUSTOM_AUTH/login', json=params)
-
-# Logout
-client.logout()
 ```
-
-### Manage tokens
-
-```python
-token = client.create_token(policies=['root'], lease='1h')
-
-current_token = client.lookup_token()
-some_other_token = client.lookup_token('xxx')
-
-client.revoke_token('xxx')
-client.revoke_token('yyy', orphan=True)
-
-client.revoke_token_prefix('zzz')
-
-client.renew_token('aaa')
-```
-
-### Managing tokens using accessors
-
-```python
-token = client.create_token(policies=['root'], lease='1h')
-token_accessor = token['auth']['accessor']
-
-same_token = client.lookup_token(token_accessor, accessor=True)
-client.revoke_token(token_accessor, accessor=True)
-```
-
-### Wrapping/unwrapping a token
-
-```python
-wrap = client.create_token(policies=['root'], lease='1h', wrap_ttl='1m')
-result = self.client.unwrap(wrap['wrap_info']['token'])
-```
-
-### Manipulate auth backends
-
-```python
-backends = client.list_auth_backends()
-
-client.enable_auth_backend('userpass', mount_point='customuserpass')
-client.disable_auth_backend('github')
-```
-
-### Manipulate secret backends
-
-```python
-backends = client.list_secret_backends()
-
-client.enable_secret_backend('aws', mount_point='aws-us-east-1')
-client.disable_secret_backend('mysql')
-
-client.tune_secret_backend('generic', mount_point='test', default_lease_ttl='3600s', max_lease_ttl='8600s')
-client.get_secret_backend_tuning('generic', mount_point='test')
-
-client.remount_secret_backend('aws-us-east-1', 'aws-east')
-```
-
-### Manipulate policies
-
-```python
-policies = client.list_policies() # => ['root']
-
-policy = """
-path "sys" {
-  policy = "deny"
-}
-
-path "secret" {
-  policy = "write"
-}
-
-path "secret/foo" {
-  policy = "read"
-}
-"""
-
-client.set_policy('myapp', policy)
-
-client.delete_policy('oldthing')
-
-policy = client.get_policy('mypolicy')
-
-# Requires pyhcl to automatically parse HCL into a Python dictionary
-policy = client.get_policy('mypolicy', parse=True)
-```
-
-### Manipulate audit backends
-
-```python
-backends = client.list_audit_backends()
-
-options = {
-    'path': '/tmp/vault.log',
-    'log_raw': True,
-}
-
-client.enable_audit_backend('file', options=options, name='somefile')
-client.disable_audit_backend('oldfile')
-```
-
-### Initialize and seal/unseal
-
-```python
-print(client.is_initialized()) # => False
-
-shares = 5
-threshold = 3
-
-result = client.initialize(shares, threshold)
-
-root_token = result['root_token']
-keys = result['keys']
-
-print(client.is_initialized()) # => True
-
-print(client.is_sealed()) # => True
-
-# unseal with individual keys
-client.unseal(keys[0])
-client.unseal(keys[1])
-client.unseal(keys[2])
-
-# unseal with multiple keys until threshold met
-client.unseal_multi(keys)
-
-print(client.is_sealed()) # => False
-
-client.seal()
-
-print(client.is_sealed()) # => True
-```
-
-## Testing
-
-Integration tests will automatically start a Vault server in the background. Just make sure
-the latest `vault` binary is available in your `PATH`.
-
-1. [Install Vault](https://vaultproject.io/docs/install/index.html) or execute `VAULT_BRANCH=release scripts/install-vault-release.sh`
-2. [Install Tox](http://tox.readthedocs.org/en/latest/install.html)
-3. Run tests: `make test`
-
-## Contributing
-
-Feel free to open pull requests with additional features or improvements!
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -E -a
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = hvac
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -0,0 +1 @@
+.. mdinclude:: ../CHANGELOG.md
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,70 @@
+# -*- coding: utf-8 -*-
+# Configuration file for the Sphinx documentation builder.
+
+
+# -- Path setup --------------------------------------------------------------
+# Set up import path to allow the autodoc extension to find the local module code.
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = u'hvac'
+copyright = u'2018, Ian Unruh, Jeffrey Hogan'
+author = u'Ian Unruh, Jeffrey Hogan'
+
+# The short X.Y version
+version = u'0.6.1'
+# The full version, including alpha/beta/rc tags
+release = u'0.6.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.coverage',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+    'm2r',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+language = None
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'hvacdoc'
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+epub_author = author
+epub_publisher = author
+epub_copyright = copyright
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+# -- Extension configuration -------------------------------------------------
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -0,0 +1 @@
+.. mdinclude:: ../CONTRIBUTING.md
diff --git a/docs/examples/approle_auth_method.rst b/docs/examples/approle_auth_method.rst
@@ -0,0 +1,9 @@
+Approle Auth Method
+===================
+
+Authentication
+--------------
+
+.. code:: python
+
+    client.auth_approle('MY_ROLE_ID', 'MY_SECRET_ID')