Permalink
Browse files

Cleaning up for docs

  • Loading branch information...
1 parent 2585d1b commit c76408c2c002dcab6bfc3148760ee58a19cbe05e @coleifer committed May 3, 2012
Showing with 883 additions and 61 deletions.
  1. +48 −35 README.rst
  2. +153 −0 docs/Makefile
  3. +242 −0 docs/conf.py
  4. +195 −0 docs/index.rst
  5. +190 −0 docs/make.bat
  6. +55 −26 generic_aggregation/utils.py
View
@@ -5,54 +5,67 @@ django-generic-aggregation
annotate() and aggregate() for generically-related data. also a handy function
for filtering GFK-model querysets.
-the use of annotate() and aggregate() require a ``GenericRelation``.
+Use django's `GenericRelation <https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/#reverse-generic-relations>`_ where possible,
+as this can make the queries generated more efficient by using a JOIN rather
+than a subquery.
-Examples
---------
-You want the most commented on blog entries::
+installation
+------------
+
+::
+
+ # install from pypi
+ pip install django-generic-aggregation
+
+ # or install via git
+ pip install -e git+git://github.com/coleifer/django-generic-aggregation.git#egg=generic_aggregation
- >>> from django.contrib.comments.models import Comment
- >>> from django.db.models import Count
- >>> from blog.models import BlogEntry
- >>> from generic_aggregation import generic_annotate
- >>> annotated = generic_annotate(BlogEntry.objects.all(), Comment, Count('comments__id'))
+examples
+--------
- >>> for entry in annotated:
- ... print entry.title, entry.score
+The examples below assume the following simple models:
- The most popular 5
- The second best 4
- Nobody commented 0
+::
+ class Rating(models.Model):
+ rating = models.IntegerField()
+ object_id = models.IntegerField()
+ content_type = models.ForeignKey(ContentType)
+ content_object = GenericForeignKey(ct_field='content_type', fk_field='object_id')
+
+ class Food(models.Model):
+ name = models.CharField(max_length=50)
+ ratings = generic.GenericRelation(Rating) # reverse generic relation
-You want to figure out which items are highest rated::
- from django.db.models import Sum, Avg
+You want to figure out which items are highest rated (generic_annotate)
- # assume a Food model and a generic Rating model
- apple = Food.objects.create(name='apple')
+::
+
+ from django.db.models import Avg
+
+ food_qs = Food.objects.filter(name__startswith='a')
+ generic_annotate(food_qs, Rating, Avg('ratings__rating'))
- # create some ratings on the food
- Rating.objects.create(content_object=apple, rating=3)
- Rating.objects.create(content_object=apple, rating=5)
- Rating.objects.create(content_object=apple, rating=7)
+ # you can mix and match queryset / model
+ generic_annotate(food_qs, Rating.objects.all(), Avg('ratings__rating'))
+
+You want the average rating for all foods that start with 'a' (generic_aggregate)
+
+::
+
+ food_qs = Food.objects.filter(name__startswith='a')
+ generic_aggregate(food_qs, Rating, Avg('ratings__rating'))
- >>> aggregate = generic_aggregate(Food, Rating, Sum('ratings__rating'))
- >>> print aggregate
- 15
+You want to only display ratings for foods that start with 'a' (generic_filter)
- >>> aggregate = generic_aggregate(Food, Rating.objects.all(), Avg('ratings__rating'))
- >>> print aggregate
- 5
+ food_qs = Food.objects.filter(name__startswith='a')
+ generic_filter(Rating.objects.all(), food_qs)
-You want to only display ratings for comments made on a given site:
- >>> from django.contrib.comments.models import Comment
- >>> from generic_aggregation import generic_filter
- >>> ratings = Rating.objects.all() # <--- grab all the ratings
- >>> comments = Comment.objects.filter(site=Site.objects.get_current())
- >>> siteified_ratings = generic_filter(ratings, comments)
+documentation
+-------------
-Check the tests - there are more examples there. Tested with postgres & sqlite
+http://django-generic-aggregation.readthedocs.org/
View
@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/django-generic-aggregation.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-generic-aggregation.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/django-generic-aggregation"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django-generic-aggregation"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
Oops, something went wrong. Retry.

0 comments on commit c76408c

Please sign in to comment.