From 8e07203d1818ca8cd059ac5654f6ea5ea3efa2af Mon Sep 17 00:00:00 2001 From: Ilan Date: Mon, 13 Jul 2015 15:30:12 +0200 Subject: [PATCH] Adding sphinx builds to Travis * added default module django_q * set build mode to nit-picky * warnings raise errors Want to make sure the docs are neat and build on Travis , to make it easier to accept doc pull requests --- .travis.yml | 2 +- django_q/__init__.py | 5 +++-- docs/Makefile | 2 +- docs/admin.rst | 1 + docs/cluster.rst | 12 +++++++----- docs/conf.py | 4 ++-- docs/install.rst | 8 +++++--- docs/monitor.rst | 1 + docs/schedules.rst | 28 ++++++++++++++-------------- docs/tasks.rst | 7 ++++--- 10 files changed, 39 insertions(+), 31 deletions(-) diff --git a/.travis.yml b/.travis.yml index 7669f57..31bed91 100644 --- a/.travis.yml +++ b/.travis.yml @@ -19,7 +19,7 @@ install: script: - coverage run --source=django_q -m py.test - - sphinx-build -nW -c docs/conf.py + - sphinx-build -b html -d docs/_build/doctrees -nW docs docs/_build/html after_success: - coveralls diff --git a/django_q/__init__.py b/django_q/__init__.py index a02a2c5..e37e91f 100644 --- a/django_q/__init__.py +++ b/django_q/__init__.py @@ -5,8 +5,9 @@ myPath = os.path.dirname(os.path.abspath(__file__)) sys.path.insert(0, myPath) from .tasks import async, schedule, result, fetch -from .models import Task, Schedule +from .models import Task, Schedule, Success, Failure +from .cluster import Cluster -VERSION = (0, 3, 3) +VERSION = (0, 3, 4) default_app_config = 'django_q.apps.DjangoQConfig' diff --git a/docs/Makefile b/docs/Makefile index 678418c..f59c132 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -nW SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build diff --git a/docs/admin.rst b/docs/admin.rst index 329875d..f1c3fd4 100644 --- a/docs/admin.rst +++ b/docs/admin.rst @@ -1,4 +1,5 @@ .. _admin_page: +.. py:currentmodule:: django_q Admin pages =========== diff --git a/docs/cluster.rst b/docs/cluster.rst index 8075a01..1c293b9 100644 --- a/docs/cluster.rst +++ b/docs/cluster.rst @@ -1,6 +1,8 @@ Cluster ======= +.. py:currentmodule:: django_q + Django Q uses Python's multiprocessing module to manage a pool of workers that will handle your tasks. Start your cluster using Django's `manage.py` command:: @@ -46,7 +48,7 @@ You can have multiple clusters on multiple machines, working on the same queue a - They connect to the same Redis server. - They use the same cluster name. See :ref:`configuration` -- They share the same :const:`SECRET_KEY` +- They share the same `SECRET_KEY` Using a Procfile ---------------- @@ -111,7 +113,7 @@ Scheduler Once a minute the scheduler checks for any scheduled task that should be starting. - Creates a task from the schedule -- Subtracts 1 from :attr:`Schedule.repeats` +- Subtracts 1 from :attr:`django_q.Schedule.repeats` - Sets the next run time if there are repeats left or if its negative. .. _stop_procedure: @@ -162,7 +164,7 @@ Reference .. py:attribute:: sentinel - returns the :class:`multiprocessing.Process` containing the :class:`Sentinel`. + returns the :class:`multiprocessing.Process` containing the :ref:`sentinel`. .. py:attribute:: timeout @@ -170,11 +172,11 @@ Reference .. py:attribute:: start_event - A :class:`multiprocessing.Event` indicating if the :class:`Sentinel` has finished starting the cluster + A :class:`multiprocessing.Event` indicating if the :ref:`sentinel` has finished starting the cluster .. py:attribute:: stop_event - A :class:`multiprocessing.Event` used to instruct the :class:`Sentinel` to initiate the :ref:`stop_procedure` + A :class:`multiprocessing.Event` used to instruct the :ref:`sentinel` to initiate the :ref:`stop_procedure` .. py:attribute:: is_starting diff --git a/docs/conf.py b/docs/conf.py index 4cda9db..e55d1b0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -72,7 +72,7 @@ author = 'Ilan Steemers' # The short X.Y version. version = '0.3' # The full version, including alpha/beta/rc tags. -release = '0.3.3' +release = '0.3.4' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -100,7 +100,7 @@ exclude_patterns = ['_build'] # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -# add_module_names = True +add_module_names = False # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. diff --git a/docs/install.rst b/docs/install.rst index 941685a..39b0ec8 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -6,7 +6,7 @@ Installation $ pip install django-q -- Add :mod:`django_q` to :const:`INSTALLED_APPS` in your projects :file:`settings.py`:: +- Add :mod:`django_q` to `INSTALLED_APPS` in your projects :file:`settings.py`:: INSTALLED_APPS = ( # other apps @@ -25,7 +25,7 @@ Installation Configuration ------------- -Configuration is handled via the :const:`Q_ClUSTER` dictionary in your :file:`settings.py` +Configuration is handled via the `Q_ClUSTER` dictionary in your :file:`settings.py` .. code:: python @@ -130,7 +130,7 @@ of the cache connection you want to use:: .. tip:: - Django Q uses your :const:`SECRET_KEY` to encrypt task packages and prevent task crossover. So make sure you have it set up in your Django settings. + Django Q uses your `SECRET_KEY` to encrypt task packages and prevent task crossover. So make sure you have it set up in your Django settings. Requirements ------------ @@ -166,3 +166,5 @@ Django Q is tested for Python 2.7 and 3.4 $ pip install hiredis This C library maintained by the core Redis team is faster than the standard PythonParser during high loads. + +.. py:module:: django_q \ No newline at end of file diff --git a/docs/monitor.rst b/docs/monitor.rst index 63535c6..b657f34 100644 --- a/docs/monitor.rst +++ b/docs/monitor.rst @@ -1,5 +1,6 @@ Monitor ======= +.. py:currentmodule::django_q.monitor The cluster monitor shows information about all the Q clusters connected to your project. diff --git a/docs/schedules.rst b/docs/schedules.rst index abca5fd..b2c1780 100644 --- a/docs/schedules.rst +++ b/docs/schedules.rst @@ -1,24 +1,24 @@ Schedules ========= +.. py:currentmodule:: django_q Schedule -------- -Schedules are regular Django models. You can manage them through the :ref:`admin_page` or directly from your code with the :func:`schedule` function or the :class:`Schedule` model: +Schedules are regular Django models. +You can manage them through the :ref:`admin_page` or directly from your code with the :func:`schedule` function or the :class:`Schedule` model: .. code:: python from django_q import Schedule, schedule # Use the schedule wrapper - schedule('math.copysign', 2, -2, hook='hooks.print_result', schedule_type=Schedule.DAILY) # Or create the object directly - Schedule.objects.create(func='math.copysign', hook='hooks.print_result', args='2,-2', @@ -31,24 +31,24 @@ Management Commands If you want to schedule regular Django management commands, you can use the :mod:`django.core.management` module to make a wrapper function which you can schedule in Django Q:: - # tasks.py - from django.core import management - - # wrapping `manage.py clearsessions` - def clear_sessions_command(): - return management.call_command('clearsessions') + # tasks.py + from django.core import management - # now you can schedule it to run every hour - from django_q import schedule + # wrapping `manage.py clearsessions` + def clear_sessions_command(): + return management.call_command('clearsessions') + + # now you can schedule it to run every hour + from django_q import schedule + + schedule('tasks.clear_sessions_command', schedule_type='H') - schedule('tasks.clear_sessions_command', schedule_type='H') - Reference --------- -.. py:function:: schedule(func, *args, hook=None, schedule_type='O', repeats=-1, next_run=now() , **kwargs) +.. py:function:: schedule(func, *args, hook=None, schedule_type='O', repeats=-1, next_run=now() , **kwargs) Creates a schedule diff --git a/docs/tasks.rst b/docs/tasks.rst index de83f58..c16b842 100644 --- a/docs/tasks.rst +++ b/docs/tasks.rst @@ -1,10 +1,11 @@ Tasks ===== +.. py:currentmodule:: django_q Async ----- -Use :func:`async` from your code to quickly offload tasks to the :mod:`cluster`: +Use :func:`async` from your code to quickly offload tasks to the :class:`Cluster`: .. code:: python @@ -83,9 +84,9 @@ Reference :param func: The task function to execute :param args: The arguments for the task function - :type func: str or object + :type func: object :param hook: Optional function to call after execution - :type hook: str or object + :type hook: object :param bool sync: If set to True, async will simulate a task execution :param redis: Optional redis connection :param kwargs: Keyword arguments for the task function