#334 - Updating sphinx generated docs

CONTRIBUTING.rst

@@ -76,13 +76,12 @@ Ready to contribute? Here's how to set up ``brewtils`` for local development.
 
    Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
+5. When you're done making changes, check that your changes pass flake8 and the tests::
 
     $ flake8 brewtils test
-    $ nosetests
-    $ tox
+    $ pytest test
 
-   To get flake8 and tox, just pip install them into your virtualenv.
+   To get flake8 and pytest, just pip install them into your virtualenv.
 
 6. Commit your changes and push your branch to GitHub::
 
@@ -101,14 +100,13 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
-3. The pull request should work for Python 2.7, 3.5, and 3.6. Check
-   https://travis-ci.org/beer-garden/brewtils/pull_requests
+3. The pull request should work for Python 2.7 and 3.5+. Check
+   https://github.com/beer-garden/brewtils/pulls
    and make sure that the tests pass for all supported Python versions.
 
 Tips
 ----
 
 To run a subset of tests::
 
-$ nosetests test/models_test.py:SystemTest.test_instance_names
-
+$ pytest test/models_test.py::TestSystem::test_instance_names

Makefile

@@ -57,7 +57,7 @@ clean-build: ## remove build artifacts
 	find . -name '*.egg' -exec rm -f {} +
 
 clean-docs: ## remove doc artifacts
-	rm -f docs/$(MODULE_NAME).rst
+	rm -f docs/$(MODULE_NAME)*.rst
 	rm -f docs/modules.rst
 
 clean-python: ## remove Python file artifacts

brewtils/config.py

@@ -49,7 +49,7 @@ def main():
     from failing on the unknown argument.
 
     Returns:
-        :ArgumentParser: Argument parser with Brewtils arguments loaded
+        ArgumentParser: Argument parser with Brewtils arguments loaded
     """
     parser = ArgumentParser()
 
@@ -71,7 +71,7 @@ def get_connection_info(cli_args=None, argument_parser=None, **kwargs):
         **kwargs: Additional configuration overrides
 
     Returns:
-        :dict: Parameters needed to make a connection to Beergarden
+        dict: Parameters needed to make a connection to Beergarden
     """
     config = load_config(cli_args=cli_args, argument_parser=argument_parser, **kwargs)
 
@@ -108,7 +108,7 @@ def load_config(
         **kwargs: Additional configuration overrides
 
     Returns:
-        :obj:`box.Box`: The resolved configuration object
+        box.Box: The resolved configuration object
     """
     spec = YapconfSpec(SPECIFICATION, env_prefix="BG_")
 
@@ -172,8 +172,7 @@ def _translate_kwargs(**kwargs):
     - Convert "url_prefix" to "bg_url_prefix"
 
     Args:
-        kwargs: Keyword arguments to translate
-
+        **kwargs: Keyword arguments to translate
     """
     name_map = [
         # (old_name, new_name, show_deprecation)

brewtils/decorators.py

@@ -276,7 +276,11 @@ def echo(self, message):
 
 
 def parameters(*args, **kwargs):
-    """Decorator for specifying multiple Parameter definitions at once
+    """
+    .. deprecated:: 3.0
+        Will be removed in version 4.0. Please use ``@command`` instead.
+
+    Decorator for specifying multiple Parameter definitions at once
 
     This can be useful for commands which have a large number of complicated
     parameters but aren't good candidates for a Model.
@@ -853,6 +857,10 @@ def _signature_validate(cmd, method):
 
 
 def command_registrar(*args, **kwargs):
+    """
+    .. deprecated: 3.0
+        Will be removed in 4.0. Use ``@system`` instead.
+    """
     _deprecate(
         "Looks like you're using the '@command_registrar' decorator. Heads up - this "
         "name will be removed in version 4.0, please use '@system' instead. Thanks!"
@@ -861,6 +869,10 @@ def command_registrar(*args, **kwargs):
 
 
 def register(*args, **kwargs):
+    """
+    .. deprecated: 3.0
+        Will be removed in 4.0. Use ``@command`` instead.
+    """
     _deprecate(
         "Looks like you're using the '@register' decorator. Heads up - this name will "
         "be removed in version 4.0, please use '@command' instead. Thanks!"
@@ -869,6 +881,10 @@ def register(*args, **kwargs):
 
 
 def plugin_param(*args, **kwargs):
+    """
+    .. deprecated: 3.0
+        Will be removed in 4.0. Use ``@parameter`` instead.
+    """
     _deprecate(
         "Looks like you're using the '@plugin_param' decorator. Heads up - this name "
         "will be removed in version 4.0, please use '@parameter' instead. Thanks!"

brewtils/models.py

@@ -802,7 +802,10 @@ def get_instance_by_id(self, id, raise_missing=False):
         return None
 
     def get_instance(self, name):
-        """DEPRECATED: Please use get_instance_by_name instead"""
+        """
+        .. deprecated::3.0
+           Will be removed in 4.0. Use ``get_instance_by_name`` instead
+        """
         _deprecate(
             "Heads up! This method is deprecated, please use get_instance_by_name"
         )

brewtils/pika.py

@@ -417,14 +417,14 @@ def finish_message(self, basic_deliver, future):
         an exception:
 
         - If there is no exception it acks the message
-        - If there is an exception:
-          - If the exception is an instance of DiscardMessageException it nacks the
-            message and does not requeue it
-          - If the exception is an instance of RepublishRequestException it will
-            construct an entirely new BlockingConnection, use that to publish a new
-            message, and then ack the original message
-          - If the exception is not an instance of either the panic_event is set and
-            the consumer will self-destruct
+        - If there is an exception
+            - If the exception is an instance of DiscardMessageException it acks the
+              message and does not requeue it
+            - If the exception is an instance of RepublishRequestException it will
+              construct an entirely new BlockingConnection, use that to publish a new
+              message, and then ack the original message
+            - If the exception is not an instance of either the panic_event is set and
+              the consumer will self-destruct
 
         Also, if there's ever an error acking a message the panic_event is set and the
         consumer will self-destruct.
@@ -545,11 +545,9 @@ def on_connection_closed(self, connection, *args):
         Args:
             connection: The connection
             args: Tuple of arguments describing why the connection closed
-                pika < 1:
-                    reply_code: Numeric code indicating close reason
-                    reply_text: String describing close reason
-                pika >= 1:
-                    exc: Exception describing close
+                For pika < 1: reply_code (Numeric code indicating close reason),
+                reply_text (String describing close reason).  For pika >= 1
+                exc (Exception describing close).
 
         Returns:
             None
@@ -595,11 +593,9 @@ def on_channel_closed(self, channel, *args):
         Args:
             channel: The channel
             args: Tuple of arguments describing why the channel closed
-                pika < 1:
-                    reply_code: Numeric code indicating close reason
-                    reply_text: String describing close reason
-                pika >= 1:
-                    exc: Exception describing close
+                For pika < 1: reply_code (Numeric code indicating close reason),
+                reply_text (String describing close reason).  For pika >= 1
+                exc (Exception describing close).
 
         Returns:
             None