Skip to content

Commit 6e91036

Browse files
author
Ask Solem
committed
Added Sphinx documentation and distro utils
1 parent 7e6ebab commit 6e91036

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

66 files changed

+3816
-27
lines changed

‎README.rst

+36-4
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,47 @@ databases (`SQLAlchemy`_ / `Django`_) is also available.
3939
.. _`operate with other languages using webhooks`:
4040
http://ask.github.com/celery/userguide/remote-tasks.html
4141

42+
.. contents::
43+
:local:
44+
45+
Using django-celery
46+
===================
47+
48+
To enable ``django-celery`` for your project you need to add ``djcelery`` to
49+
``INSTALLED_APPS``::
50+
51+
INSTALLED_APPS += ("djcelery", )
52+
53+
Everything works the same as described in the `Celery User Manual`_, except you need
54+
to invoke the programs through ``manage.py``:
55+
56+
===================================== =====================================
57+
**Program** **Replace with**
58+
===================================== =====================================
59+
``celeryd`` ``python manage.py celeryd``
60+
``celerybeat`` ``python manage.py celerybeat``
61+
``camqadm`` ``python manage.py camqadm``
62+
``celeryev`` ``python manage.py celeryev``
63+
===================================== =====================================
64+
65+
and instead of storing configuration values in ``celeryconfig.py``, you should use
66+
your Django projects ``settings.py`` module.
67+
68+
If you're getting started for the first time you should read
69+
`Getting started with django-celery`_
70+
4271
Documentation
4372
=============
4473

45-
The `latest documentation`_ contains user guides, tutorials and an API reference.
46-
Be sure to also read the `Celery User Manual`_.
74+
The `Celery User Manual`_ contains user guides, tutorials and an API
75+
reference. Also the `django-celery documentation`_, contains information
76+
about the Django integration.
4777

48-
.. _`latest documentation`: http://celeryproject.org/docs/django-celery/
78+
.. _`django-celery documentation`:
79+
http://celeryproject.org/docs/django-celery/
4980
.. _`Celery User Manual`: http://celeryproject.org/docs/
81+
.. _`Getting started with django-celery`:
82+
http://celeryq.org/docs/django-celery/getting-started/first-steps-with-django.html
5083

5184
Installation
5285
=============
@@ -82,7 +115,6 @@ You can clone the repository by doing the following::
82115

83116
$ git clone git://github.com/ask/django-celery.git
84117

85-
86118
Getting Help
87119
============
88120

‎contrib/release/doc4allmods

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
#!/bin/bash
2+
3+
PACKAGE="$1"
4+
SKIP_PACKAGES="$PACKAGE tests management urls"
5+
SKIP_FILES="djcelery.management.rst
6+
djcelery.management.commands.rst
7+
djcelery.management.commands.celeryd.rst
8+
djcelery.management.commands.celerybeat.rst
9+
djcelery.management.commands.celeryev.rst
10+
djcelery.contrib.rst
11+
djcelery.backends.rst"
12+
13+
modules=$(find "$PACKAGE" -name "*.py")
14+
15+
failed=0
16+
for module in $modules; do
17+
dotted=$(echo $module | sed 's/\//\./g')
18+
name=${dotted%.__init__.py}
19+
name=${name%.py}
20+
rst=$name.rst
21+
skip=0
22+
for skip_package in $SKIP_PACKAGES; do
23+
[ $(echo "$name" | cut -d. -f 2) == "$skip_package" ] && skip=1
24+
done
25+
for skip_file in $SKIP_FILES; do
26+
[ "$skip_file" == "$rst" ] && skip=1
27+
done
28+
29+
if [ $skip -eq 0 ]; then
30+
if [ ! -f "docs/reference/$rst" ]; then
31+
if [ ! -f "docs/internals/reference/$rst" ]; then
32+
echo $rst :: FAIL
33+
failed=1
34+
fi
35+
fi
36+
fi
37+
done
38+
39+
exit $failed

‎contrib/release/sphinx-to-rst.py

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
#!/usr/bin/even/python
2+
import os
3+
import re
4+
import sys
5+
6+
dirname = ""
7+
8+
RE_CODE_BLOCK = re.compile(r'.. code-block:: (.+?)\s*$')
9+
RE_INCLUDE = re.compile(r'.. include:: (.+?)\s*$')
10+
RE_REFERENCE = re.compile(r':(.+?):`(.+?)`')
11+
12+
13+
def include_file(lines, pos, match):
14+
global dirname
15+
orig_filename = match.groups()[0]
16+
filename = os.path.join(dirname, orig_filename)
17+
fh = open(filename)
18+
try:
19+
old_dirname = dirname
20+
dirname = os.path.dirname(orig_filename)
21+
try:
22+
lines[pos] = sphinx_to_rst(fh)
23+
finally:
24+
dirname = old_dirname
25+
finally:
26+
fh.close()
27+
28+
29+
def replace_code_block(lines, pos, match):
30+
lines[pos] = ""
31+
curpos = pos - 1
32+
# Find the first previous line with text to append "::" to it.
33+
while True:
34+
prev_line = lines[curpos]
35+
if not prev_line.isspace():
36+
prev_line_with_text = curpos
37+
break
38+
curpos -= 1
39+
40+
if lines[prev_line_with_text].endswith(":"):
41+
lines[prev_line_with_text] += ":"
42+
else:
43+
lines[prev_line_with_text] += "::"
44+
45+
TO_RST_MAP = {RE_CODE_BLOCK: replace_code_block,
46+
RE_REFERENCE: r'``\2``',
47+
RE_INCLUDE: include_file}
48+
49+
50+
def _process(lines):
51+
lines = list(lines) # non-destructive
52+
for i, line in enumerate(lines):
53+
for regex, alt in TO_RST_MAP.items():
54+
if callable(alt):
55+
match = regex.match(line)
56+
if match:
57+
alt(lines, i, match)
58+
line = lines[i]
59+
else:
60+
lines[i] = regex.sub(alt, line)
61+
return lines
62+
63+
64+
def sphinx_to_rst(fh):
65+
return "".join(_process(fh))
66+
67+
68+
if __name__ == "__main__":
69+
global dirname
70+
dirname = os.path.dirname(sys.argv[1])
71+
fh = open(sys.argv[1])
72+
try:
73+
print(sphinx_to_rst(fh))
74+
finally:
75+
fh.close()

‎contrib/release/verify-reference-index.sh

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#!/bin/bash
2+
3+
verify_index() {
4+
modules=$(grep "celery." "$1" | \
5+
perl -ple's/^\s*|\s*$//g;s{\.}{/}g;')
6+
retval=0
7+
for module in $modules; do
8+
if [ ! -f "$module.py" ]; then
9+
if [ ! -f "$module/__init__.py" ]; then
10+
echo "Outdated reference: $module"
11+
retval=1
12+
fi
13+
fi
14+
done
15+
16+
return $retval
17+
}
18+
19+
verify_index docs/reference/index.rst && \
20+
verify_index docs/internals/reference/index.rst
21+

‎djcelery/loaders.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ def on_worker_init(self):
6767

6868

6969
def autodiscover():
70-
"""Include tasks for all applications in :setting:`INSTALLED_APPS`."""
70+
"""Include tasks for all applications in ``INSTALLED_APPS``."""
7171
from django.conf import settings
7272
global _RACE_PROTECTION
7373

‎docs/.static/.keep

Whitespace-only changes.

‎docs/Makefile

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
PAPER =
8+
9+
# Internal variables.
10+
PAPEROPT_a4 = -D latex_paper_size=a4
11+
PAPEROPT_letter = -D latex_paper_size=letter
12+
ALLSPHINXOPTS = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
13+
14+
.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
15+
16+
help:
17+
@echo "Please use \`make <target>' where <target> is one of"
18+
@echo " html to make standalone HTML files"
19+
@echo " pickle to make pickle files"
20+
@echo " json to make JSON files"
21+
@echo " htmlhelp to make HTML files and a HTML help project"
22+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
23+
@echo " changes to make an overview over all changed/added/deprecated items"
24+
@echo " linkcheck to check all external links for integrity"
25+
26+
clean:
27+
-rm -rf .build/*
28+
29+
html:
30+
mkdir -p .build/html .build/doctrees
31+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html
32+
@echo
33+
@echo "Build finished. The HTML pages are in .build/html."
34+
35+
coverage:
36+
mkdir -p .build/coverage .build/doctrees
37+
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) .build/coverage
38+
@echo
39+
@echo "Build finished."
40+
41+
pickle:
42+
mkdir -p .build/pickle .build/doctrees
43+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle
44+
@echo
45+
@echo "Build finished; now you can process the pickle files."
46+
47+
web: pickle
48+
49+
json:
50+
mkdir -p .build/json .build/doctrees
51+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) .build/json
52+
@echo
53+
@echo "Build finished; now you can process the JSON files."
54+
55+
htmlhelp:
56+
mkdir -p .build/htmlhelp .build/doctrees
57+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
58+
@echo
59+
@echo "Build finished; now you can run HTML Help Workshop with the" \
60+
".hhp project file in .build/htmlhelp."
61+
62+
latex:
63+
mkdir -p .build/latex .build/doctrees
64+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
65+
@echo
66+
@echo "Build finished; the LaTeX files are in .build/latex."
67+
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
68+
"run these through (pdf)latex."
69+
70+
changes:
71+
mkdir -p .build/changes .build/doctrees
72+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes
73+
@echo
74+
@echo "The overview file is in .build/changes."
75+
76+
linkcheck:
77+
mkdir -p .build/linkcheck .build/doctrees
78+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
79+
@echo
80+
@echo "Link check complete; look for any errors in the above output " \
81+
"or in .build/linkcheck/output.txt."

‎docs/_ext/applyxrefs.py

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
"""Adds xref targets to the top of files."""
2+
3+
import sys
4+
import os
5+
6+
testing = False
7+
8+
DONT_TOUCH = (
9+
'./index.txt',
10+
)
11+
12+
13+
def target_name(fn):
14+
if fn.endswith('.txt'):
15+
fn = fn[:-4]
16+
return '_' + fn.lstrip('./').replace('/', '-')
17+
18+
19+
def process_file(fn, lines):
20+
lines.insert(0, '\n')
21+
lines.insert(0, '.. %s:\n' % target_name(fn))
22+
try:
23+
f = open(fn, 'w')
24+
except IOError:
25+
print("Can't open %s for writing. Not touching it." % fn)
26+
return
27+
try:
28+
f.writelines(lines)
29+
except IOError:
30+
print("Can't write to %s. Not touching it." % fn)
31+
finally:
32+
f.close()
33+
34+
35+
def has_target(fn):
36+
try:
37+
f = open(fn, 'r')
38+
except IOError:
39+
print("Can't open %s. Not touching it." % fn)
40+
return (True, None)
41+
readok = True
42+
try:
43+
lines = f.readlines()
44+
except IOError:
45+
print("Can't read %s. Not touching it." % fn)
46+
readok = False
47+
finally:
48+
f.close()
49+
if not readok:
50+
return (True, None)
51+
52+
#print fn, len(lines)
53+
if len(lines) < 1:
54+
print("Not touching empty file %s." % fn)
55+
return (True, None)
56+
if lines[0].startswith('.. _'):
57+
return (True, None)
58+
return (False, lines)
59+
60+
61+
def main(argv=None):
62+
if argv is None:
63+
argv = sys.argv
64+
65+
if len(argv) == 1:
66+
argv.extend('.')
67+
68+
files = []
69+
for root in argv[1:]:
70+
for (dirpath, dirnames, filenames) in os.walk(root):
71+
files.extend([(dirpath, f) for f in filenames])
72+
files.sort()
73+
files = [os.path.join(p, fn) for p, fn in files if fn.endswith('.txt')]
74+
#print files
75+
76+
for fn in files:
77+
if fn in DONT_TOUCH:
78+
print("Skipping blacklisted file %s." % fn)
79+
continue
80+
81+
target_found, lines = has_target(fn)
82+
if not target_found:
83+
if testing:
84+
print '%s: %s' % (fn, lines[0]),
85+
else:
86+
print "Adding xref to %s" % fn
87+
process_file(fn, lines)
88+
else:
89+
print "Skipping %s: already has a xref" % fn
90+
91+
if __name__ == '__main__':
92+
sys.exit(main())

0 commit comments

Comments
 (0)