Overhauled documentation. Credit for the toctree restructuring goes to …

…@jameshiew.

.gitignore

@@ -43,6 +43,7 @@ nosetests.xml
 
 # Sphinx
 docs/_build
+docs/_static
 htmlcov
 
 # OSX

.travis.yml

@@ -20,6 +20,7 @@ env:
   - TOXENV=py36-djangomaster
   - TOXENV=checkmigrations
   - TOXENV=flake8
+  - TOXENV=docs
 
 matrix:
   fast_finish: true

djstripe/models.py

@@ -1397,10 +1397,6 @@ class Event(StripeObject):
     event that just happened. Events are processed in detail by their respective
     models (charge events by the Charge model, etc).
 
-    Events are initially **UNTRUSTED**, as it is possible for any web entity to
-    post any data to our webhook url. Data posted may be valid Stripe information,
-    garbage, or even malicious. The 'valid' flag in this model monitors this.
-
     **API VERSIONING**
 
     This is a tricky matter when it comes to webhooks. See the discussion here_.
@@ -1416,7 +1412,7 @@ class Event(StripeObject):
     2) retrieve the referenced object (e.g. the Charge, the Customer, etc) using
        the plugin's supported API version.
     3) process that event using the retrieved object which will, only now, be in
-    a format that you are certain to understand
+       a format that you are certain to understand
 
     # = Mapping the values of this field isn't currently on our roadmap.
         Please use the stripe dashboard to check the value of this field instead.
@@ -3326,6 +3322,10 @@ def is_expired(self):
 class WebhookEventTrigger(models.Model):
     """
     An instance of a request that reached the server endpoint for Stripe webhooks.
+
+    Webhook Events are initially **UNTRUSTED**, as it is possible for any web entity to
+    post any data to our webhook url. Data posted may be valid Stripe information,  garbage, or even malicious.
+    The 'valid' flag in this model monitors this.
     """
     id = models.BigAutoField(primary_key=True)
     remote_ip = models.GenericIPAddressField(

djstripe/stripe_objects.py

@@ -2,23 +2,24 @@
 
 import warnings
 
-from . import models
+from .models import StripeObject as MovedStripeObject
+from .models import Account, Card, Charge, Coupon, Customer, Event, Invoice, Payout, Plan, Subscription, Transfer
 
 
 warnings.warn(
     "djstripe.stripe_objects is a deprecated module, please use djstripe.models",
     DeprecationWarning
 )
 
-StripeObject = models.StripeObject
-StripeCharge = models.Charge
-StripeCustomer = models.Customer
-StripeEvent = models.Event
-StripePayout = models.Payout
-StripeCard = models.Card
-StripeCoupon = models.Coupon
-StripeInvoice = models.Invoice
-StripePlan = models.Plan
-StripeSubscription = models.Subscription
-StripeAccount = models.Account
-StripeTransfer = models.Transfer
+StripeObject = MovedStripeObject
+StripeCharge = Charge
+StripeCustomer = Customer
+StripeEvent = Event
+StripePayout = Payout
+StripeCard = Card
+StripeCoupon = Coupon
+StripeInvoice = Invoice
+StripePlan = Plan
+StripeSubscription = Subscription
+StripeAccount = Account
+StripeTransfer = Transfer

djstripe/webhooks.py

@@ -15,11 +15,7 @@
 Each registration entry is a list of processors
 Each processor in these lists is a function to be called
 The function signature is:
-     <Event object> <event data dict> <event type> <event sub type>
-
-The <event data dict> parameter should be a dict() structure, as received from Stripe
-on webhook. This dict contains an 'object' member and also, sometimes, a 'previous_attributes'
-member.
+     <Event object>
 
 There is also a "global registry" which is just a list of processors (as defined above)
 

docs/conf.py

@@ -12,14 +12,11 @@
 # serve to show the default.
 from __future__ import absolute_import, division, print_function, unicode_literals
 
-import inspect
 import os
 import sys
 
 import django
 from django.conf import settings
-from django.utils.encoding import force_text
-from django.utils.html import strip_tags
 
 import djstripe  # noqa
 
@@ -58,7 +55,11 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinxcontrib_django',
+    'sphinx.ext.viewcode'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -288,55 +289,3 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
-
-
-def process_docstring(app, what, name, obj, options, lines):
-    """
-    Auto list fields from django models.
-    https://djangosnippets.org/snippets/2533/#c5977
-    """
-
-    # This causes import errors if left outside the function
-    from django.db import models
-
-    # Only look at objects that inherit from Django's base model class
-    if inspect.isclass(obj) and issubclass(obj, models.Model):
-        # Grab the field list from the meta class
-        fields = obj._meta.get_fields()
-
-        for field in [_field for _field in fields if _field.name not in ("id", "created", "modified")]:
-            # Skip ManyToOneRel and ManyToManyRel fields which have no 'verbose_name' or 'help_text'
-            if not hasattr(field, 'verbose_name') or (hasattr(field, 'deprecated') and field.deprecated):
-                continue
-
-            # Decode and strip any html out of the field's help text
-            help_text = strip_tags(force_text(field.help_text))
-
-            # Decode and capitalize the verbose name, for use if there isn't
-            # any help text
-            verbose_name = force_text(field.verbose_name).capitalize()
-
-            if help_text:
-                # Add the model field to the end of the docstring as a param
-                # using the help text as the description
-                lines.append(u':param %s: %s' % (field.name, help_text))
-            else:
-                # Add the model field to the end of the docstring as a param
-                # using the verbose name as the description
-                lines.append(u':param %s: %s' % (field.name, verbose_name))
-
-            # Add the field's type to the docstring
-            if isinstance(field, models.ForeignKey):
-                to = field.remote_field.model
-                lines.append(u':type %s: %s to :class:`~%s.%s`' % (field.name, type(field).__name__,
-                                                                   to.__module__, to.__name__))
-            else:
-                lines.append(u':type %s: %s' % (field.name, type(field).__name__))
-
-    # Return the extended docstring
-    return lines
-
-
-def setup(app):
-    # Register the docstring processor with sphinx
-    app.connect('autodoc-process-docstring', process_docstring)

docs/index.rst

@@ -1,8 +1,3 @@
-.. complexity documentation master file, created by
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Django + Stripe Made Easy
 --------------------------------
 
@@ -23,20 +18,48 @@ Contents
 ---------
 
 .. toctree::
-   :maxdepth: 2
+   :caption: Getting Started
 
    installation
-   usage
-   models
-   settings
-   cookbook
-   contributing
-   authors
-   history
+
+.. toctree::
+   :caption: Usage
+
+   usage/checking_customer_subscription
+   usage/subscribing_customers.rst
+   usage/one_off_charges.rst
+   usage/restricting_access.rst
+   usage/managing_subscriptions.rst
+   usage/creating_invoices.rst
+   usage/running_reports.rst
+   usage/webhooks.rst
+   usage/manually_syncing_with_stripe.rst
+   usage/cookbook
+
+.. toctree::
+   :caption: Reference
+   :glob:
+
+   reference/context_managers.rst
+   reference/decorators.rst
+   reference/enums.rst
+   reference/managers.rst
+   reference/middleware.rst
+   reference/models.rst
+   reference/settings.rst
+   reference/utils.rst
+
+.. toctree::
+   :caption: Project
+
+   project/contributing.rst
+   project/authors.rst
+   project/history.rst
+   project/support.rst
 
 Constraints
 ------------
 
 1. For stripe.com only
 2. Only use or support well-maintained third-party libraries
-3. For modern Python and Django
+3. For modern Python and Django