diff --git a/awslimitchecker/checker.py b/awslimitchecker/checker.py
index ee671e78..d937a3db 100644
--- a/awslimitchecker/checker.py
+++ b/awslimitchecker/checker.py
@@ -138,7 +138,7 @@ def get_service_names(self):
     def find_usage(self, service=None, use_ta=True):
         """
         For each limit in the specified service (or all services if
-        ``service`` is ``None``), query the AWS API via :py:pkg:`boto`
+        ``service`` is ``None``), query the AWS API via :py:mod:`boto`
         and find the current usage amounts for that limit.
 
         This method updates the ``current_usage`` attribute of the
@@ -147,8 +147,7 @@ def find_usage(self, service=None, use_ta=True):
 
         :param service: :py:class:`~._AwsService` name, or ``None`` to
           check all services.
-        :type services: :py:obj:`None` or :py:obj:`string` service name
-        to_get = self.services
+        :type service: :py:obj:`None`, or :py:obj:`string` service name to get
         :param use_ta: check Trusted Advisor for information on limits
         :type use_ta: bool
         """
@@ -169,11 +168,12 @@ def set_limit_overrides(self, override_dict, override_ta=True):
         the same form as that returned by :py:meth:`~.get_limits`,
         i.e. service_name (str) keys to nested dict of limit_name
         (str) to limit value (int) like:
+        ::
 
             {
                 'EC2': {
-                    'Running On-Demand t2.micro Instances': 1000,
-                    'Running On-Demand r3.4xlarge Instances': 1000,
+                  'Running On-Demand t2.micro Instances': 1000,
+                  'Running On-Demand r3.4xlarge Instances': 1000,
                 }
             }
 
@@ -192,7 +192,8 @@ def set_limit_overrides(self, override_dict, override_ta=True):
         :param override_ta: whether or not to use this value even if Trusted
           Advisor supplies limit information
         :type override_ta: bool
-        :raises: ValueError if limit_name is not known to the service instance
+        :raises: :py:exc:`exceptions.ValueError` if limit_name is not known to
+          the service instance
         """
         for svc_name in override_dict:
             for lim_name in override_dict[svc_name]:
@@ -247,6 +248,7 @@ def set_threshold_overrides(self, override_dict):
         keys 'percent' or 'count', to an integer value.
 
         Example:
+        ::
 
             {
                 'EC2': {
diff --git a/awslimitchecker/limit.py b/awslimitchecker/limit.py
index a821c265..9a12a404 100644
--- a/awslimitchecker/limit.py
+++ b/awslimitchecker/limit.py
@@ -37,8 +37,13 @@
 ################################################################################
 """
 
+#: indicates a limit value that came from hard-coded defaults in awslimitchecker
 SOURCE_DEFAULT = 0
+
+#: indicates a limit value that came from user-defined limit overrides
 SOURCE_OVERRIDE = 1
+
+#: indicates a limit value that came from Trusted Advisor
 SOURCE_TA = 2
 
 
@@ -105,7 +110,7 @@ def set_limit_override(self, limit_value, override_ta=True):
         :param limit_value: the new limit value
         :type limit_value: int
         :param override_ta: whether or not to also override Trusted
-        Advisor information
+          Advisor information
         :type override_ta: bool
         """
         self.limit_override = limit_value
@@ -124,12 +129,17 @@ def _set_ta_limit(self, limit_value):
 
     def get_limit_source(self):
         """
-        Return :py:const:`~.SOURCE_DEFAULT` if :py:meth:`~.get_limit`
-        returns the default limit, :py:const:`~.SOURCE_OVERRIDE` if it returns
-        a manually-overridden limit, or :py:const:`~.SOURCE_TA` if it
-        returns a limit from Trusted Advisor.
+        Return :py:const:`~awslimitchecker.limit.SOURCE_DEFAULT` if
+        :py:meth:`~.get_limit` returns the default limit,
+        :py:const:`~awslimitchecker.limit.SOURCE_OVERRIDE` if it returns a
+        manually-overridden limit, or
+        :py:const:`~awslimitchecker.limit.SOURCE_TA` if it returns a limit from
+        Trusted Advisor.
 
-        :rtype: bool
+        :returns: one of :py:const:`~awslimitchecker.limit.SOURCE_DEFAULT`,
+          :py:const:`~awslimitchecker.limit.SOURCE_OVERRIDE`, or
+          :py:const:`~awslimitchecker.limit.SOURCE_TA`
+        :rtype: int
         """
         if self.limit_override is not None and (
                 self.override_ta is True or
@@ -174,13 +184,13 @@ def get_current_usage_str(self):
         "<unknown>".
 
         If the limit has only one current usage instance, this will be
-        that instance's :py:meth:`~.AwsLimitUsage.__repr__` value.
+        that instance's :py:meth:`~.AwsLimitUsage.__str__` value.
 
         If the limit has more than one current usage instance, this
         will be the a string of the form ``max: X (Y)`` where ``X`` is
-        the :py:meth:`~.AwsLimitUsage.__repr__` value of the instance
+        the :py:meth:`~.AwsLimitUsage.__str__` value of the instance
         with the maximum value, and ``Y`` is a comma-separated list
-        of the :py:meth:`~.AwsLimitUsage.__repr__` values of all usage
+        of the :py:meth:`~.AwsLimitUsage.__str__` values of all usage
         instances in ascending order.
 
         :returns: representation of current usage
diff --git a/awslimitchecker/services/base.py b/awslimitchecker/services/base.py
index 2cfd7217..04671a47 100644
--- a/awslimitchecker/services/base.py
+++ b/awslimitchecker/services/base.py
@@ -153,7 +153,7 @@ def set_limit_override(self, limit_name, value, override_ta=True):
         :param value: the new value to set for the limit
         :type value: int
         :param override_ta: whether or not to also override Trusted
-        Advisor information
+          Advisor information
         :type override_ta: bool
         :raises: ValueError if limit_name is not known to this service
         """
diff --git a/awslimitchecker/trustedadvisor.py b/awslimitchecker/trustedadvisor.py
index 63bfdbf1..8c9a3b6a 100644
--- a/awslimitchecker/trustedadvisor.py
+++ b/awslimitchecker/trustedadvisor.py
@@ -79,12 +79,14 @@ def _poll(self):
         each key is a limit name and each value the current numeric limit.
 
         e.g.:
+        ::
 
-        {
-            'EC2': {
-                'SomeLimit': 10,
+            {
+                'EC2': {
+                    'SomeLimit': 10,
+                }
             }
-        }
+
         """
         logger.info("Beginning TrustedAdvisor poll")
         tmp = self._get_limit_check_id()
diff --git a/docs/build_generated_docs.py b/docs/build_generated_docs.py
index 0439474c..8a86c0f2 100644
--- a/docs/build_generated_docs.py
+++ b/docs/build_generated_docs.py
@@ -133,6 +133,7 @@ def build_limits(checker):
             limit_info += sformat.format(name=lname, limit=limit)
         # footer
         limit_info += sep
+        limit_info += "\n"
 
     # TA limit list
     ta_info = """
diff --git a/docs/source/_static/.gitkeep b/docs/source/_static/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/source/cli_usage.rst b/docs/source/cli_usage.rst
index 85a4290b..8b4d2fdb 100644
--- a/docs/source/cli_usage.rst
+++ b/docs/source/cli_usage.rst
@@ -174,12 +174,12 @@ using their IDs).
    (venv)$ awslimitchecker -u
    AutoScaling/Auto Scaling groups                        42
    AutoScaling/Launch configurations                      50
-   EBS/Active snapshots                                   948
-   EBS/Active volumes                                     851
+   EBS/Active snapshots                                   949
+   EBS/Active volumes                                     853
    EBS/General Purpose (SSD) volume storage (GiB)         4123
    (...)
    VPC/Rules per network ACL                              max: acl-0c279569=4 (acl-0c279569=4, acl-c6d7 (...)
-   VPC/Subnets per VPC                                    max: vpc-1ee8937b=11 (vpc-a926c2cc=4, vpc-c30 (...)
+   VPC/Subnets per VPC                                    max: vpc-73ec9716=11 (vpc-a926c2cc=4, vpc-c30 (...)
    VPC/VPCs                                               4
 
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
index ab3b9b85..17dd4d45 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -286,6 +286,8 @@
 autoclass_content = 'init'
 autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'special-members', 'show-inheritance']
 
+nitpick_ignore = [('py:class', 'ABCMeta')]
+
 # exclude module docstrings - see http://stackoverflow.com/a/18031024/211734
 def remove_module_docstring(app, what, name, obj, options, lines):
     if what == "module":
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
index e21dea2b..f0aa0f32 100644
--- a/docs/source/getting_started.rst
+++ b/docs/source/getting_started.rst
@@ -105,4 +105,4 @@ Or as a python dict:
     c = AwsLimitChecker()
     iam_policy = c.get_required_iam_policy()
 
-You can also view the required permissions for the current version of awslimitchecker at :ref:`Required IAM Permissions <.iam_policy>`.
+You can also view the required permissions for the current version of awslimitchecker at :ref:`Required IAM Permissions <iam_policy>`.
diff --git a/docs/source/internals.rst b/docs/source/internals.rst
index 5fcef033..957ff82d 100644
--- a/docs/source/internals.rst
+++ b/docs/source/internals.rst
@@ -20,7 +20,7 @@ Service Classes are instantiated, they build a dict of all of their limits, corr
 with an :py:class:`~awslimitchecker.limit.AwsLimit` object. The Service Class constructors *must not* make any network
 connections; connections are created lazily as needed and stored as a class attribute. This allows us to inspect the
 services, limits and default limit values without ever connecting to AWS (this is also used to generate the
-:ref:`Supported Limits <_limits>` documentation automatically).
+:ref:`Supported Limits <limits>` documentation automatically).
 
 When :py:class:`~awslimitchecker.checker.AwsLimitChecker` is instantiated, it imports :py:mod:`~awslimitchecker.services`
 which in turn creates instances of all ``awslimitchecker.services.*`` classes and adds them to a dict mapping the
@@ -28,7 +28,7 @@ string Service Name to the Service Class instance. These instances are used for
 
 So, once an instance of :py:class:`~awslimitchecker.checker.AwsLimitChecker` is created, we should have instant access
 to the services and limits without any connection to AWS. This is utilized by the ``--list-services`` and
-``--list-defaults`` options for the :ref:`command line client <_cli>`.
+``--list-defaults`` options for the :ref:`command line client <cli_usage>`.
 
 .. _internals.trusted_advisor:
 
@@ -36,8 +36,8 @@ Trusted Advisor
 -----------------
 
 When :py:class:`~awslimitchecker.checker.AwsLimitChecker` is initialized, it also initializes an instance of
-:py:class:`~awslimitchecker.trustedadvisor.TrustedAdvisor`. In :py:meth:`~.AwsLimitchecker.get_limits`,
-:py:meth:`~.AwsLimitchecker.find_usage` and :py:meth:`~.AwsLimitchecker.check_thresholds`, when called with
+:py:class:`~awslimitchecker.trustedadvisor.TrustedAdvisor`. In :py:meth:`~.AwsLimitChecker.get_limits`,
+:py:meth:`~.AwsLimitChecker.find_usage` and :py:meth:`~.AwsLimitChecker.check_thresholds`, when called with
 ``use_ta == True`` (the default), :py:meth:`~.TrustedAdvisor.update_limits` is called on the TrustedAdvisor
 instance.
 
diff --git a/docs/source/limits.rst b/docs/source/limits.rst
index 60e54ce3..54ce37e4 100644
--- a/docs/source/limits.rst
+++ b/docs/source/limits.rst
@@ -88,6 +88,7 @@ Limit                             Default
 Auto Scaling groups :sup:`(TA)`   20 
 Launch configurations :sup:`(TA)` 100
 ================================= ===
+
 EBS
 ++++
 
@@ -101,6 +102,7 @@ Magnetic volume storage (GiB) :sup:`(TA)`              20
 Provisioned IOPS (SSD) storage (GiB) :sup:`(TA)`       20   
 Provisioned IOPS :sup:`(TA)`                           40000
 ====================================================== =====
+
 EC2
 ++++
 
@@ -166,6 +168,7 @@ Running On-Demand t2.small instances              20
 Security groups per VPC                           100
 VPC security groups per elastic network interface 5  
 ================================================= ===
+
 ELB
 ++++
 
@@ -175,6 +178,7 @@ Limit                             Default
 Active load balancers :sup:`(TA)` 20 
 Listeners per load balancer       100
 ================================= ===
+
 ElastiCache
 ++++++++++++
 
@@ -188,6 +192,7 @@ Parameter Groups  20
 Security Groups   50
 Subnet Groups     50
 ================= ==
+
 RDS
 ++++
 
@@ -208,6 +213,7 @@ Subnet Groups                            20
 Subnets per Subnet Group                 20    
 VPC Security Groups                      5     
 ======================================== ======
+
 VPC
 ++++
 
@@ -224,3 +230,4 @@ VPCs :sup:`(TA)`              5
 ============================= ===
 
 
+
diff --git a/docs/source/python_usage.rst b/docs/source/python_usage.rst
index 947d984f..ea0090ed 100644
--- a/docs/source/python_usage.rst
+++ b/docs/source/python_usage.rst
@@ -6,7 +6,7 @@ Python Usage
 
 The full feature set of awslimitchecker is available through the Python API.
 This page attempts to document some examples of usage, but the best resources are
-:py:mod:`~AwsLimitchecker.runner`, the command line wrapper, and the
+:py:mod:`~.runner`, the command line wrapper, and the
 :ref:`API documentation <modindex>`.
 
 Simple Examples
@@ -17,7 +17,7 @@ Many of these examples use :py:mod:`pprint` to make output a bit nicer.
 Instantiating the Class
 ++++++++++++++++++++++++
 
-Here we import and instantiate the :py:class:`class <~.AwsLimitChecker>`; note that we also setup
+Here we import and instantiate the :py:class:`~.AwsLimitChecker` class; note that we also setup
 Python's :py:mod:`logging` module, which is used by ``awslimitchecker``.
 We also import :py:mod:`pprint` to make the output nicer.
 
@@ -120,6 +120,7 @@ As this limit is per-VPC, our string representation of the current usage include
 crossed the critical threshold:
 
 .. code-block:: pycon
+
    >>> for usage in result['EC2']['Security groups per VPC'].get_criticals():
    ...     print(str(usage))
    ... 
diff --git a/tox.ini b/tox.ini
index b84bbe02..96075970 100644
--- a/tox.ini
+++ b/tox.ini
@@ -67,14 +67,13 @@ commands =
     pip freeze
     rst2html.py --halt=2 README.rst /dev/null
     sphinx-apidoc awslimitchecker awslimitchecker/tests -o {toxinidir}/docs/source -e -f -M
+    python {toxinidir}/docs/build_generated_docs.py
     # link check
     # -n runs in nit-picky mode
     # -W turns warnings into errors
-    # @TODO re-enable this and add back -n and -W
-    # sphinx-build -a -n -b linkcheck {toxinidir}/docs/source {toxinidir}/docs/build/html
+    sphinx-build -a -b linkcheck {toxinidir}/docs/source {toxinidir}/docs/build/html
     # build
-    python {toxinidir}/docs/build_generated_docs.py
-    sphinx-build -a -n -b html {toxinidir}/docs/source {toxinidir}/docs/build/html
+    sphinx-build -a -b html {toxinidir}/docs/source {toxinidir}/docs/build/html
 
 [testenv:cov]
 # this runs coverage report