improving documentation

Author: samuelcolvin

Makefile

@@ -45,3 +45,7 @@ clean:
 docs:
 	make -C docs html
 	@echo "open file://`pwd`/docs/_build/html/index.html"
+
+.PHONY: deploy-docs
+deploy-docs: docs
+	ghp-import -m "update docs" -p docs/_build/html/

arq/jobs.py

@@ -1,6 +1,8 @@
 """
 :mod:`jobs`
 ===========
+
+Defines the ``Job`` class and decedents which deal with encoding and decoding job data.
 """
 from datetime import datetime
 
@@ -85,9 +87,10 @@ def __repr__(self):
 
 class DatetimeJob(Job):
     """
-    Alternative Job which
+    Alternative Job which copes with datetimes. None timezone naïve dates are supported but
+    the returned datetimes will use python datetime's ``timezone`` class to define the timezone
+    regardless of the timezone class originally used on the datetime object.
     """
-
     @staticmethod
     def msgpack_encoder(obj):
         if isinstance(obj, datetime):

arq/main.py

@@ -1,6 +1,8 @@
 """
 :mod:`main`
 ===========
+
+Defines the main ``Actor`` class and ``concurrent`` decorator for using arq from within your code.
 """
 import inspect
 import logging

arq/testing.py

@@ -1,6 +1,14 @@
 """
 :mod:`testing`
 ==============
+
+pytest plugin and other utilities useful when writing tests for code using arq.
+
+include the plugin in your tests's `conftest.py` file with::
+
+    pytest_plugins = 'arq.testing'
+
+See arq's own tests for examples of usage.
 """
 import asyncio
 import contextlib

arq/utils.py

@@ -1,6 +1,8 @@
 """
-:mod:`utilities`
-================
+:mod:`utils`
+============
+
+Utilises for running arq used by modules.
 """
 import asyncio
 import base64

arq/worker.py

@@ -1,6 +1,8 @@
 """
 :mod:`worker`
 =============
+
+Responsible for executing jobs in the worker processes.
 """
 import asyncio
 import logging
@@ -310,7 +312,15 @@ def import_string(file_path, attr_name):
     return attr
 
 
-def start_worker(worker_path, worker_class, burst, loop=None):
+def start_worker(worker_path: str, worker_class: str, burst: bool, loop: asyncio.AbstractEventLoop=None):
+    """
+    Run from within the subprocess to load the worker class and execute jobs.
+
+    :param worker_path: full path to the python file containing the worker definition
+    :param worker_class: name of the worker class to be loaded and used
+    :param burst: whether or not to run in burst mode
+    :param loop: asyncio loop use to or None
+    """
     worker_cls = import_string(worker_path, worker_class)
     worker = worker_cls(burst=burst, loop=loop)
     work_logger.info('Starting %s on worker process pid=%d', worker_cls.__name__, os.getpid())
@@ -327,6 +337,9 @@ def start_worker(worker_path, worker_class, burst, loop=None):
 
 
 class RunWorkerProcess:
+    """
+    Responsible for starting a process to run the worker, monitoring it and possibly killing it.
+    """
     def __init__(self, worker_path, worker_class, burst=False):
         signal.signal(signal.SIGINT, self.handle_sig)
         signal.signal(signal.SIGTERM, self.handle_sig)

docs/conf.py

@@ -134,7 +134,16 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'github_user': 'samuelcolvin',
+    'github_repo': 'arq',
+    'travis_button': True,
+    'codecov_button': True,
+    'page_width': '1200px',
+    'github_banner': True,
+
+    'github_type': 'star',
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -184,7 +193,11 @@
 # Custom sidebar templates, maps document names to template names.
 #
 html_sidebars = {
-   '**': ['localtoc.html', 'searchbox.html'],
+    '**': [
+        'about.html',
+        'localtoc.html',
+        'searchbox.html',
+    ]
 }
 
 # Additional templates that should be rendered to pages, maps page names to

docs/index.rst

@@ -4,7 +4,7 @@ arq
 .. toctree::
    :maxdepth: 2
 
-|Build Status| |Coverage| |pypi| |license|
+|pypi| |license|
 
 
 Job queues in python with asyncio, redis and msgpack.
@@ -61,7 +61,7 @@ API Reference
    :members:
 
 .. automodule:: arq.jobs
-   :members:
+   :members: Job, DatetimeJob
 
 .. automodule:: arq.logs
    :members:
@@ -79,10 +79,6 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
-.. |Build Status| image:: https://travis-ci.org/samuelcolvin/arq.svg?branch=master
-   :target: https://travis-ci.org/samuelcolvin/arq
-.. |Coverage| image:: https://codecov.io/gh/samuelcolvin/arq/branch/master/graph/badge.svg
-   :target: https://codecov.io/gh/samuelcolvin/arq
 .. |pypi| image:: https://img.shields.io/pypi/v/arq.svg
    :target: https://pypi.python.org/pypi/arq
 .. |license| image:: https://img.shields.io/pypi/l/arq.svg

tests/requirements.txt

@@ -3,6 +3,7 @@ coverage
 docutils
 flake8
 isort
+ghp-import
 pep8
 pytest
 pytest-cov