Fix sphinx errors, warnings

Author: bmos

docs/_template.rst

@@ -1,37 +1,33 @@
+#############
 YourConnector
-=============
+#############
 
-********
 Overview
-********
+========
 
 Provide a brief description of the tool your connector integrates with.
 
-Describe which features your connector implements and which features it doesn't. For example,
-you could specify that `YourConnector` implements the `thing` and `place` endpoints of the API, but
-does not implement the `person` endpoints.
+Describe which features your connector implements and which features it doesn't.
+For example, you could specify that ``YourConnector`` implements the ``thing`` and ``place`` endpoints of the API,
+but does not implement the ``person`` endpoints.
 
-==========
 Quickstart
 ==========
 
-Provide a few examples of how to use `YourConnector`. Each example should be limited to a
-few lines of code. Use the [Sphinx Markup syntax](https://www.sphinx-doc.org/en/1.5/markup/code.html)
+Provide a few examples of how to use ``YourConnector``.
+Each example should be limited to a few lines of code.
+Use the `Sphinx Markup syntax <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code>`__
 to embed your examples. Be sure to provide an explanation of exactly what the code is doing.
 
-**Example 1**
-
 .. code-block:: python
+   :caption: Get all things updated since Jan 01 2020
 
-  from parsons import YourConnector
-  yc = YourConnector()
-  table = yc.get_things(updated_since='2020-01-01')
-
-This example shows how to get all of the things updated since the first day of the year 2020.
+   from parsons import YourConnector
+   yc = YourConnector()
+   table = yc.get_things(updated_since='2020-01-01')
 
-***
 API
-***
+====
 
 .. autoclass:: parsons.yourconnector.yourconnector.YourConnector
    :inherited-members:

docs/actblue.rst

@@ -1,54 +1,55 @@
+#######
 ActBlue
-=======
+#######
 
-********
 Overview
-********
+========
 
-The ActBlue class allows you to interact with the ActBlue CSV API. Users of this Parsons integration can generate CSVs and
+The :class:`~parsons.actblue.actblue.ActBlue` class allows you to interact with the ActBlue CSV API.
+Users of this Parsons integration can generate CSVs and
 manipulate entity CSV data within the Parsons table format.
 
-.. note::
+.. admonition:: Authentication
 
-  Authentication
-    In order to use this class you must generate and use a Client UUID and Client Secret set of credentials. Instructions for
-    generating the set of keys can be found within the `CSV API documentation <https://secure.actblue.com/docs/csv_api#authentication>`_.
+   In order to use this class you must generate and use a Client UUID and Client Secret set of credentials. Instructions for
+   generating the set of keys can be found within the `ActBlue CSV API Authentication Documentation`_.
 
-==========
 Quickstart
 ==========
 
-To instantiate the ActBlue class, you can either store your ``ACTBLUE_CLIENT_UUID`` and ``ACTBLUE_CLIENT_SECRET`` keys as environment
+To instantiate the :class:`~parsons.actblue.actblue.ActBlue` class, you can either store your
+``ACTBLUE_CLIENT_UUID`` and ``ACTBLUE_CLIENT_SECRET`` keys as environment
 variables or pass them in as arguments:
 
 .. code-block:: python
+   :caption: Use API key environment variables
 
    from parsons import ActBlue
-
-   # First approach: Use API key environment variables
-
-   # In bash, set your environment variables like so:
-   # export ACTBLUE_CLIENT_UUID='MY_UUID'
-   # export ACTBLUE_CLIENT_SECRET='MY_SECRET'
    actblue = ActBlue()
 
-   # Second approach: Pass API keys as arguments
+.. code-block:: python
+   :caption: Pass API keys as arguments
+
+   from parsons import ActBlue
    actblue = ActBlue(actblue_client_uuid='MY_UUID', actblue_client_secret='MY_SECRET')
 
-You can then make a request to generate a CSV and save its data to a Parsons table using the main helper method, ``get_contributions()``:
+You can then make a request to generate a CSV and save its data to a Parsons table using the main helper method,
+:meth:`~parsons.actblue.actblue.ActBlue.get_contributions`:
 
 .. code-block:: python
+   :caption: Create Parsons table with entity CSV data for the month of January 2020
 
-    # Create Parsons table with entity CSV data
-    parsons_table = actblue.get_contributions(csv_type='paid_contributions', date_range_start='2020-01-01', date_range_end='2020-02-01')
+   parsons_table = actblue.get_contributions(
+       csv_type='paid_contributions',
+       date_range_start='2020-01-01',
+       date_range_end='2020-02-01'
+   )
 
-The above example shows how to create a Parsons table with paid contribution data of your entity for the month of January 2020. In
-addition to 'paid_contributions', the other options for ``csv_type`` are 'refunded_contributions' and 'managed_form_contributions'.
-
-***
 API
-***
+====
 
 .. autoclass:: parsons.actblue.actblue.ActBlue
    :inherited-members:
    :members:
+
+.. _ActBlue CSV API Authentication Documentation: https://secure.actblue.com/docs/csv_api#authentication

docs/action_builder.rst

@@ -1,53 +1,57 @@
+##############
 Action Builder
-==============
+##############
 
-********
 Overview
-********
+========
 
-`Action Builder <https://actionbuilder.org/>`_ is an online tool for field organizing, with an
+`Action Builder <https://www.actionbuilder.org/>`__ is an online tool for field organizing, with an
 original use-case designed for the Labor context. While it has essentially no built-in outreach
 capabilities, it does provide robust record and relationship storage, including the ability to
 create custom record types. For more information, see
-`Action Builder developer docs <https://www.actionbuilder.org/docs/v1/index.html>`_
-
-.. note::
-
-  Custom Fields/Tags
-    Action Builder custom fields are treated as tags in both the SQL Mirror, and the API. This
-    means that, with a couple exceptions such as date, values must be created ahead of time to be
-    applied to a record. Each tag has two layers of taxonomy above it as well, that appear slightly
-    differently in the SQL Mirror and in the API. In the SQL Mirror, each tag has a
-    ``tag_category``, and each category has a ``tag_group``. In the API, the equivalents are called
-    ``tag_field`` and ``tag_section``, respectively (closer to the naming in the UI). Tags can be
-    applied on Connections as well as on Entities.
-
-***********
-Quick Start
-***********
-
-To instantiate a class, you can either pass in the API token as an argument or set the
-``ACTION_BUILDER_API_TOKEN`` environmental variable. The subdomain at which you access the UI must
-also be provided. If all calls from this object will be to the same Campaign in Action Builder,
-an optional campaign argument may also be supplied. If not supplied when instantiating, campaign
+`Action Builder developer docs <https://www.actionbuilder.org/docs/v1/index.html>`__
+
+.. admonition:: Custom Fields/Tags
+
+   Action Builder custom fields are treated as tags in both the SQL Mirror, and the API. This
+   means that, with a couple exceptions such as date, values must be created ahead of time to be
+   applied to a record. Each tag has two layers of taxonomy above it as well, that appear slightly
+   differently in the SQL Mirror and in the API. In the SQL Mirror, each tag has a
+   ``tag_category``, and each category has a ``tag_group``. In the API, the equivalents are called
+   ``tag_field`` and ``tag_section``, respectively (closer to the naming in the UI). Tags can be
+   applied on Connections as well as on Entities.
+
+Quickstart
+==========
+
+To instantiate the :class:`~parsons.action_builder.action_builder.ActionBuilder` class,
+you can either pass in the API token as an argument or set the ``ACTION_BUILDER_API_TOKEN``
+environmental variable. The subdomain at which you access the UI must also be provided.
+If all calls from this object will be to the same Campaign in Action Builder, an optional
+campaign argument may also be supplied. If not supplied when instantiating, campaign
 may be passed to individual methods, instead.
 
 .. code-block:: python
+   :caption: Use API credentials via environmental variables
 
    from parsons import ActionBuilder
-
-   # First approach: Use API credentials via environmental variables
    bldr = ActionBuilder(subdomain='yourorgsubdomain')
 
-   # Second approach: Pass API credentials as arguments
+.. code-block:: python
+   :caption: Pass API credentials as arguments
+
+   from parsons import ActionBuilder
    bldr = ActionBuilder(api_token='MY_API_TOKEN', subdomain='yourorgsubdomain')
 
-   # Third approach: Include campaign argument
-    bldr = ActionBuilder(
-        api_token = 'MY_API_TOKEN',
-        subdomain = 'yourorgsubdomain',
-        campaign = 'your-desired-campaign-id'
-    )
+.. code-block:: python
+   :caption: Include campaign argument
+
+   from parsons import ActionBuilder
+   bldr = ActionBuilder(
+       api_token = 'MY_API_TOKEN',
+       subdomain = 'yourorgsubdomain',
+       campaign = 'your-desired-campaign-id',
+   )
 
 You can then call various endpoints:
 
@@ -83,10 +87,13 @@ You can then call various endpoints:
         tag_data = tag_data
     )
 
-***
 API
-***
+====
 
 .. autoclass:: parsons.action_builder.action_builder.ActionBuilder
    :inherited-members:
    :members:
+
+.. _ActionBuilder Person Endpoint Documentation: https://www.actionbuilder.org/docs/v1/people.html#field-names
+.. _ActionBuilder Person Signup Helper Documentation: https://www.actionbuilder.org/docs/v1/person_signup_helper.html#post
+.. _ActionBuilder Connection Helper Documentation: https://www.actionbuilder.org/docs/v1/connection_helper.html#post

docs/action_kit.rst

@@ -1,63 +1,78 @@
+#########
 ActionKit
-=========
+#########
 
-********
 Overview
-********
+========
 
-`ActionKit <https://actionkit.com/>`_ is a platform for advocacy, fundraising, and
+`ActionKit <https://actionkit.com/>`__ is a platform for advocacy, fundraising, and
 get-out-the-vote. This Parsons integration with the
-`ActionKit REST API <https://roboticdogs.actionkit.com/docs/manual/api/rest/overview.html>`_
-supports fetching, creating, and updating records of campaigns, events, mailers, orders, survey questions, transactions, and users.
-Bulk upload of new users and user updates is also supported.
+`ActionKit REST API <https://roboticdogs.actionkit.com/docs/manual/api/rest/overview.html>`__
+supports fetching, creating, and updating records of campaigns, events, mailers, orders, survey questions,
+transactions, and users. Bulk upload of new users and user updates is also supported.
 
-.. note::
+.. admonition:: Authentication
 
-  Authentication
-    ActionKit requires `HTTP Basic Auth <https://en.wikipedia.org/wiki/Basic_access_authentication>`_.
-    Clients with an ActionKit account can obtain the domain, username, and password needed
-    to access the ActionKit API. See the `ActionKit REST API Authentication <https://roboticdogs.actionkit.com/docs/manual/api/rest/overview.html#authentication>`_
-    documentation for more information on obtaining ActionKit API credentials.
+   ActionKit requires `HTTP Basic Auth <https://en.wikipedia.org/wiki/Basic_access_authentication>`__.
+   Clients with an ActionKit account can obtain the domain, username, and password needed to access the ActionKit API.
+   See the `ActionKit API Authentication Documentation`_ for more information on obtaining ActionKit API credentials.
 
-**********
 Quickstart
-**********
+==========
 
-To instantiate the ActionKit class, you can either store your ActionKit API
+To instantiate the :class:`~parsons.action_kit.action_kit.ActionKit` class, you can either store your ActionKit API
 domain, username, and password as environmental variables (``ACTION_KIT_DOMAIN``,
 ``ACTION_KIT_USERNAME``, and ``ACTION_KIT_PASSWORD``, respectively) or pass in your
 domain, username, and password as arguments:
 
 .. code-block:: python
+   :caption: Use API credentials via environmental variables
 
    from parsons import ActionKit
-
-   # First approach: Use API credentials via environmental variables
    ak = ActionKit()
 
-   # Second approach: Pass API credentials as arguments
+.. code-block:: python
+   :caption: Pass API credentials as arguments
+
+   from parsons import ActionKit
    ak = ActionKit(domain='myorg.actionkit.com', username='my_name', password='1234')
 
 You can then call various endpoints:
 
 .. code-block:: python
+   :caption: Create a new user
 
-    # Create a new user
-    ak.create_user(email='john@email', first_name='John', last_name='Smith', city='Boston')
+   ak.create_user(email='john@email', first_name='John', last_name='Smith', city='Boston')
 
-    # Fetch user fields
-    user_fields = ak.get_user(user_id='123')
+.. code-block:: python
+   :caption: Fetch user fields
 
-    # Update user fields
-    ak.update_user(user_id='123', city='New York')
+   user_fields = ak.get_user(user_id='123')
 
-    # Delete user
-    ak.delete_user(user_id='123')
+.. code-block:: python
+   :caption: Update user fields
+
+   ak.update_user(user_id='123', city='New York')
+
+.. code-block:: python
+   :caption: Delete user
+
+   ak.delete_user(user_id='123')
 
-***
 API
-***
+====
 
 .. autoclass:: parsons.action_kit.action_kit.ActionKit
    :inherited-members:
    :members:
+
+.. _ActionKit API Authentication Documentation: https://roboticdogs.actionkit.com/docs/manual/api/rest/overview.html#authentication
+.. _ActionKit API Action processing Documentation: https://roboticdogs.actionkit.com/docs/manual/api/rest/actionprocessing.html
+.. _ActionKit API Ordering Documentation: https://roboticdogs.actionkit.com/docs/manual/api/rest/overview.html#ordering
+.. _ActionKit API Uploads Documentation: https://roboticdogs.actionkit.com/docs/manual/api/rest/uploads.html
+.. _ActionKit API Autocreate_user_fields Documentation: https://roboticdogs.actionkit.com/docs/manual/api/rest/uploads.html#create-a-multipart-post-request
+.. _ActionKit API Users Documentation: https://roboticdogs.actionkit.com/docs/manual/api/rest/users.html
+.. _ActionKit API Mailer Documentation: https://roboticdogs.actionkit.com/docs/manual/api/rest/mailer.html
+.. _ActionKit API Event Search Examples: https://roboticdogs.actionkit.com/docs/manual/api/rest/examples/eventsearch.html
+.. _ActionKit Email Blackhole Documentation: https://docs.actionkit.com/docs/manual/guide/mailings_tools.html#blackhole
+.. _Django Field Lookup Documentation: https://docs.djangoproject.com/en/3.1/topics/db/queries/#field-lookups