Merge pull request #2 from ambitioninc/develop

v0.1
ambitioninc · Jul 22, 2014 · 0183533 · 0183533
2 parents 4fbcdac + 7b130b7
commit 0183533
Show file tree

Hide file tree

Showing 21 changed files with 625 additions and 42 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -5,7 +5,9 @@ python:
   - '3.4'
 install:
   - pip install flake8 nose>=1.3.0
+  - pip install -r requirements/docs.txt
   - python setup.py install
 script:
   - flake8 .
-  - python setup.py nosetests
+  - python setup.py nosetests
+  - cd docs && make html
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,3 +1,2 @@
 include README.rst
-include CONTRIBUTORS
 include LICENSE
diff --git a/README.rst b/README.rst
@@ -4,13 +4,17 @@
 
 pagerduty-api
 ===============
+pagerduty-api is a package for easily interacting with PagerDuty's API.
 
+Why?
+----
 
-I have failed to provide a good README.rst in my project, and you should shun
-me if I do any pull requests
+There are several other libraries interacting with the PagerDuty API, however none of them include
+tests and documentation.
 
 Installation
 ------------
+
 To install the latest release, type::
 
     pip install pagerduty-api
@@ -19,11 +23,18 @@ To install the latest code directly from source, type::
 
     pip install git+git://github.com/ambitioninc/pagerduty-api.git
 
+
+Requirements
+------------
+
+* Python 2.7, 3.3, 3,4
+* requests >= 2.0.0
+
 Documentation
-=============
+-------------
 
 Full documentation is available at http://pagerduty-api.readthedocs.org
 
 License
-=======
+-------
 MIT License (see LICENSE)
diff --git a/docs/Makefile b/docs/Makefile
@@ -48,7 +48,7 @@ clean:
 	rm -rf $(BUILDDIR)/*
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -W -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -29,6 +29,7 @@ def get_version():
     'sphinx.ext.intersphinx',
     #'sphinx.ext.viewcode',
 ]
+autodoc_member_order = 'bysource'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -73,7 +74,7 @@ def get_version():
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
@@ -131,4 +132,4 @@ def get_version():
   ('index', 'pagerduty-api', u'pagerduty-api Documentation',
    u'Micah Hausler', 'pagerduty-api', 'A short description',
    'Miscellaneous'),
-]
+]
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,3 +1,27 @@
-pagerduty-api Documentation
-=============================
-Please put a description here, followed by sections for configuration, basic usage, and code documentation.
+Introduction
+============
+pagerduty-api is a package for easily interacting with PagerDuty's API.
+
+Why?
+----
+
+There are several other libraries interacting with the PagerDuty API, however none of them include
+tests and documentation.
+
+Installation
+------------
+
+To install the latest release, type::
+
+    pip install pagerduty-api
+
+To install the latest code directly from source, type::
+
+    pip install git+git://github.com/ambitioninc/pagerduty-api.git
+
+
+Requirements
+------------
+
+* Python 2.7, 3.3, 3,4
+* requests >= 2.0.0
diff --git a/docs/installation.rst b/docs/installation.rst
diff --git a/docs/ref/internal_resources.rst b/docs/ref/internal_resources.rst
@@ -0,0 +1,22 @@
+Internal Resources
+==================
+
+ConfigurationException
+----------------------
+
+.. automodule:: pagerduty_api.exceptions
+.. autoclass:: pagerduty_api.exceptions.ConfigurationException
+
+IncidentKeyException
+--------------------
+
+.. autoclass:: pagerduty_api.exceptions.IncidentKeyException
+
+Resource
+--------
+
+.. automodule:: pagerduty_api.base
+.. autoclass:: pagerduty_api.base.Resource
+    :members:
+
+    .. automethod:: __init__
diff --git a/docs/ref/pagerduty_api.rst b/docs/ref/pagerduty_api.rst
@@ -1,13 +1,13 @@
-.. _ref-pagerduty_api:
+.. _ref-code-documentation:
 
-Code documentation
+Code Documentation
 ==================
 
-pagerduty_api
-------------------
+Alert
+-----
 
 .. automodule:: pagerduty_api
-.. autoclass:: pagerduty_api.pagerduty_api
+.. autoclass:: pagerduty_api.Alert
     :members:
 
-    .. automethod:: __init__
+    .. automethod:: __init__
diff --git a/docs/release_notes.rst b/docs/release_notes.rst
@@ -3,5 +3,8 @@ Release Notes
 
 v0.1
 ----
+This is the initial release of pagerduty-api.
 
-* This is the initial release of pagerduty-api.
+* Includes the ``Alert`` interface
+* Includes sphinx docs
+* python 2.7, 3.3, 3.4 compatibility
diff --git a/docs/toc.rst b/docs/toc.rst
@@ -5,7 +5,8 @@ Table of Contents
    :maxdepth: 2
 
    index
-   installation
+   usage
    ref/pagerduty_api
+   ref/internal_resources
    contributing
-   release_notes
+   release_notes
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -0,0 +1,82 @@
+Usage
+=====
+
+Configuring Alerts
+------------------
+Alerts has an environment variable will need to configure before using.
+
+PAGERDUTY_API_KEY
+~~~~~~~~~~~~~~~~~
+
+This is the API access key for authenticating to PagerDuty. This defaults to
+the environment variable ``PAGERDUTY_API_KEY`` if it is present. See
+`PagerDuty's docs on authentication`_ for more information.
+
+.. _PagerDuty's docs on authentication: http://developer.pagerduty.com/documentation/rest/authentication
+
+.. code-block:: bash
+
+    $ export PAGERDUTY_API_KEY="wieZvi9AY3uCj6zaQPZX"
+
+Using Alerts
+------------
+``pagerduty_api`` comes with an interface for PagerDuty called ``Alert``. All an
+alert needs to be instantiated is a ``service_key``. This Service API Key is a
+unique ID generated in PagerDuty for a Generic API Service.
+
+.. code-block:: python
+
+    from pagerduty_api import Alert
+
+    alert = Alert(service_key='4baa5d20cfba466a5e075b02698f455c')
+    
+
+Trigger Alert
+~~~~~~~~~~~~~
+To trigger an alert, use ``.trigger()`` on the interface. If you don't pass in an
+incident_key, one will be computed as the md5 hash of the description
+
+.. code-block:: python
+
+    from pagerduty_api import Alert
+
+
+    alert = Alert(service_key='4baa5d20cfba466a5e075b02698f455c')
+    alert.trigger(
+        description='No data received',
+        client='My Client',
+        client_url='http://mysite.com',
+        details={'some_key': 'some_value'}
+    )
+
+Acknowledge Alert
+~~~~~~~~~~~~~~~~~
+To acknowledge an alert, use ``.acknowledge()`` on the interface. If you created
+this alert with ``.trigger()``, you won't need to provide an ``incident_key``.
+
+.. code-block:: python
+
+    from pagerduty_api import Alert
+
+    alert = Alert(service_key='4baa5d20cfba466a5e075b02698f455c')
+    alert.acknowledge(
+        incident_key='0ace123ba99999160f35ea3bd381a318',
+        description='Working on it.',
+        details={'some_key': 'some_value'}
+    )
+
+Resolve Alert
+~~~~~~~~~~~~~
+To resolve an alert, use ``.resolve()`` on the interface. If you created
+this alert with ``.trigger()``, you won't need to provide an ``incident_key``.
+
+.. code-block:: python
+
+    from pagerduty_api import Alert
+
+    alert = Alert(service_key='4baa5d20cfba466a5e075b02698f455c')
+    alert.resolve(
+        incident_key='0ace123ba99999160f35ea3bd381a318',
+        description='Fixed it.',
+        details={'some_key': 'some_value'}
+    )
diff --git a/pagerduty_api/__init__.py b/pagerduty_api/__init__.py
@@ -0,0 +1,2 @@
+# flake8: noqa
+from .alerts import Alert