Documentation improvements (#527)

* add basic RTD configuration

Signed-off-by: Oleg Hoefling <[email protected]>

* include default dependencies in docs requirements

Signed-off-by: Oleg Hoefling <[email protected]>

* fix sphinx warnings, use crossrefs where possible, minor style fixes

Signed-off-by: Oleg Hoefling <[email protected]>

* Update docs/includes/introduction.txt

Co-authored-by: Asif Saif Uddin <[email protected]>

* Update .readthedocs.yaml

Co-authored-by: Asif Saif Uddin <[email protected]>

Co-authored-by: Asif Saif Uddin <[email protected]>

.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.8"
+sphinx:
+   configuration: docs/conf.py
+python:
+   install:
+   - requirements: requirements/docs.txt

django_celery_beat/models.py

@@ -57,9 +57,9 @@ def cronexp(field):
 
 
 def crontab_schedule_celery_timezone():
-    """Return timezone string from Django settings `CELERY_TIMEZONE` variable.
+    """Return timezone string from Django settings ``CELERY_TIMEZONE`` variable.
 
-    If is not defined or is not a valid timezone, return `"UTC"` instead.
+    If is not defined or is not a valid timezone, return ``"UTC"`` instead.
     """
     try:
         CELERY_TIMEZONE = getattr(
@@ -76,7 +76,8 @@ class SolarSchedule(models.Model):
     """Schedule following astronomical patterns.
 
     Example: to run every sunrise in New York City:
-    event='sunrise', latitude=40.7128, longitude=74.0060
+
+    >>> event='sunrise', latitude=40.7128, longitude=74.0060
     """
 
     event = models.CharField(
@@ -136,8 +137,9 @@ def __str__(self):
 class IntervalSchedule(models.Model):
     """Schedule executing on a regular interval.
 
-    Example: execute every 2 days
-    every=2, period=DAYS
+    Example: execute every 2 days:
+
+    >>> every=2, period=DAYS
     """
 
     DAYS = DAYS
@@ -241,9 +243,10 @@ def from_schedule(cls, schedule):
 class CrontabSchedule(models.Model):
     """Timezone Aware Crontab-like schedule.
 
-    Example:  Run every hour at 0 minutes for days of month 10-15
-    minute="0", hour="*", day_of_week="*",
-    day_of_month="10-15", month_of_year="*"
+    Example:  Run every hour at 0 minutes for days of month 10-15:
+
+    >>> minute="0", hour="*", day_of_week="*",
+    ... day_of_month="10-15", month_of_year="*"
     """
 
     #
@@ -354,8 +357,8 @@ def from_schedule(cls, schedule):
 class PeriodicTasks(models.Model):
     """Helper table for tracking updates to periodic tasks.
 
-    This stores a single row with ident=1.  last_update is updated
-    via django signals whenever anything is changed in the PeriodicTask model.
+    This stores a single row with ``ident=1``.  ``last_update`` is updated
+    via django signals whenever anything is changed in the :class:`~.PeriodicTask` model.
     Basically this acts like a DB data audit trigger.
     Doing this so we also track deletions, and not just insert/update.
     """

django_celery_beat/tzcrontab.py

@@ -35,8 +35,8 @@ def nowfunc(self):
     def is_due(self, last_run_at):
         """Calculate when the next run will take place.
 
-        Return tuple of (is_due, next_time_to_check).
-        The last_run_at argument needs to be timezone aware.
+        Return tuple of ``(is_due, next_time_to_check)``.
+        The ``last_run_at`` argument needs to be timezone aware.
 
         """
         # convert last_run_at to the schedule timezone

docs/conf.py

@@ -22,4 +22,17 @@
         'django_celery_beat.apps',
         r'django_celery_beat.migrations.*',
     ],
+    extlinks={
+      'github_project': (
+        f'https://github.com/%s',
+        'GitHub project',
+      ),
+      'github_pr': (
+        f'https://github.com/celery/django-celery-beat/pull/%s',
+        'GitHub PR #',
+      ),
+    },
+    extra_intersphinx_mapping={
+        'django-celery-results': ('https://django-celery-results.readthedocs.io/en/latest/', None),
+    },
 ))

docs/copyright.rst

@@ -11,7 +11,7 @@ Copyright |copy| 2016, Ask Solem
 
 All rights reserved.  This material may be copied or distributed only
 subject to the terms and conditions set forth in the `Creative Commons
-Attribution-ShareAlike 4.0 International`
+Attribution-ShareAlike 4.0 International
 <http://creativecommons.org/licenses/by-sa/4.0/legalcode>`_ license.
 
 You may share and adapt the material, even for commercial purposes, but