sphinx docs

docs/Makefile

@@ -0,0 +1,130 @@
+# 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) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+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 "  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/Arkestra.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Arkestra.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/Arkestra"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Arkestra"
+	@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."
+
+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."

docs/_build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 49de964e0ccce83cd2e7d1c531816b9e
+tags: fbb0d17656682115ca4d033fb2f83ba1

docs/_build/html/_sources/contacts_and_people.txt

@@ -0,0 +1,92 @@
+###################
+Contacts and People
+###################
+
+This application will help manage an institution's people, entities and addresses.
+
+It is in a very basic form, and needs to be made considerably more sophisticated, but it works and has useful functionality.
+
+It has four components:
+
+*   Sites
+*   Addresses
+*   Entities
+*   People
+
+Briefly, this is how they work.
+
+*****
+Site
+*****
+A site is a collection of Places.
+
+A university might be based at several campuses (sites) each with a number of buildings (Places), for example.
+
+At present, each site has a name, town and country.
+
+*********
+Building
+*********
+
+On each site, there will be one or more buildings, so each building is assigned to a site.
+
+A building has a name and/or number, a street name, an additional address line, and a postal code. Together with the Site, this adds up to the complete postal address for a building.
+
+******
+Entity
+******
+
+An entity is a part of an institution - a faculty, department, office, commitee, helpdesk, section, etc. Entities are arranged in a hierarchy (each entity has a parent until we get to the root of the hieararchy). The hierarchy is managed by MPTT.
+
+Some entities are just abstract entities, i.e. groups of actual entities. For example, we might have an entity called "Departments", the group of all departments.
+
+An entity can be connected to a Page in Django CMS. This way, a Page in CMS can pull in all kinds of information from other databases and publish it automatically. 
+
+For example, if a page has been assigned to an entity, a templatetag in it can publish contact details, or lists of members, or appropriate news items, and so on.
+
+Entity names are also used to build the internal or institutional part of an address, for example:
+
+Complaints Department
+Customer Services
+Yoyodyne Corporation
+[...]
+
+An option for an entity is not to display its parent's name. This would be useful where an entity is not needed in to route mail or visitors. It is also useful in cases where we might find ourselves with a silly address like:
+
+[...]
+Department of Anaesthetics
+Cardiff University School of Medicine
+Cardiff University
+
+In such a case, Cardiff University School of Medicine obviously does not want its parent's address published.
+
+Entities can also be external to the institution.
+
+******
+Person
+******
+
+People share an abstract model for contact information with entities, and this is used to build the postal part of their address.
+
+In addition, a person has a Home entity, their base within the institution. Memebrship of an entity automatically gives a person membership of all its ancestors too.
+
+They can be added to other entities too, from different parts of the hierarchy. For example a person might belong to several different committees.
+
+A simple templatetag will generate a tree of the entities within the institution, showing only those nodes that a person belongs to.
+
+A person can have a another person assigned to them for contact purposes, so that the other person's contact details are published. This would be useful for when someone is away on leave, or prefers to have communications go through a secretary or assistant.
+
+Also important is the ability to override the person's entity for address purposes. For example, if a person is:
+
+Stanley Koteks
+Top Secret Project 
+Research Labs
+Yoyodyne Corporation
+
+it might not be a good idea to publish all that information. Instead, we can override "Top Secret project" and choose something safer ("Research Labs", or even just "Yoyodyne Corporation").
+
+There are many ways in which this application can (and needs to) be developed. However it is ready to use and includes templates and templatetags demonstrating some useful functionality.
+
+Its output can be explored (when the server is up) by starting at:
+
+<http://w128.medcn.uwcm.ac.uk:8001/en/person/mr-daniele-procida/>

docs/_build/html/_sources/index.txt

@@ -0,0 +1,28 @@
+.. Arkestra documentation master file, created by
+   sphinx-quickstart on Tue May  3 19:31:41 2011.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+######################################################
+Arkestra: documentation for development and deployment
+######################################################
+
+This document refers to version |release|
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   contacts_and_people
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

docs/_build/html/_sources/installation.txt

@@ -0,0 +1,36 @@
+To install these applications:
+
+First, you need to have Django CMS 2 installed and working.
+And get django-widgetry (http://github.com/stefanfoulis/django-widgetry)
+
+
+Place contacts_and_people and news_and_events onto your PYTHONPATH.
+
+Add:
+
+    'news_and_events',
+    'contacts_and_people',
+
+to your INSTALLED_APPS.
+
+Add:
+
+    (r"^entity/(?P<slug>[-\w]+)/$", "contacts_and_people.views.entity"),
+    (r"^person/(?P<slug>[-\w]+)/$", "contacts_and_people.views.person"),
+    (r"^news/article/(?P<slug>[-\w]+)/$", "news_and_events.views.newsarticle"),
+    (r"^events/event/(?P<slug>[-\w]+)/$", "news_and_events.views.event"),
+
+    (r'^news/rss/', include('news_and_events.feeds_urls')),
+
+to your urlpatterns = patterns in urls.py.
+
+A syncdb will be required.
+
+
+these rss feeds are available:
+
+/news/rss/latest/										all news
+/news/rss/latest_by_entity/<entity-slug>/				all news entries for the entity
+/news/rss/latest_by_contact_person/<person-slug>/		all news entries where the person is the contact person
+/news/rss/latest_by_related_person/<person-slug>/		all news entries where the person is mentioned in related person
+

docs/_build/html/_sources/links.txt

@@ -0,0 +1,62 @@
+Generic Links App
+
+The links app allows generic links between any models. You need to add a setting similar to this:
+
+To register specific models that they can be links, a link_schema.py module needs to be created in
+your app. The registry system is comparable with how django.contrib.admin works.
+Every linkable needs a certain list of attributes. Either defined on the model itself or provided with a wrapper.
+A list of the needed attributes is in `links.schema_registry.ATTRIBUTES`. Be aware that 'title' and 'description'
+are also used in the autocomplete widget.
+
+There a multiple ways how you can define a link/wrapper:
+
+`from links import schema
+from news_and_events import models
+from news_and_events import admin`
+
+1. Very simple case. Your model has all the needed attributes already
+
+`schema.register(models.Event, search_fields=admin.EventAdmin.search_fields)`
+
+
+2. The attributes on the model are named different:
+
+`schema.register(models.Event, search_fields=admin.EventADmin.search_fields,
+	title='name', description='some_foreign_key.title', heading='"Event"')`
+
+Each named argument after search_fields represents a attribute the wrapper will have.
+A string means the dot noted path will be used to traverse through object, starting from
+the linked object. `description='some_foreign_key.title'` will result in using
+`theobj.some_foreign_key.title` for the title. It does not matter if the attributes are properties
+or callable methods, both work.
+
+`heading='"Event"'` will use a static string for the heading. Both `"'foo'"` and `'"bar"'` work.
+
+3. You want to do some extra calculation.
+
+This works by providing a callable that takes one argument: the linked object
+It can be a lamda function or a external function
+
+`def some_very_complicated_function(obj):
+	r = []
+	for x in obj.something.all():
+		if x.y:
+			r.append(u"foo: %s" % x.bar)
+		else:
+			r.append(u"stuff: %s" % x.bar)
+	return "<br />".join(r)
+schema.register(models.Event, search_fields=admin.EventAdmin.search_fields,
+	title=lambda obj: u"%s (%s)" % (unicode(obj), obj.active_count),
+	description=some_very_complicated_function)`
+
+
+4. You have a quite complex wrapper: make you own Wrapper subclass
+
+`from links import LinkWrapper
+class MyEventLinkWrapper(LinkWrapper):
+	search_fields = admin.EventAdmin.search_fields
+	def title(self):
+		return self.obj.something(extra=' asdfsadf')
+	def description(self):
+		return "static description"
+schema.register_wrapper(Event, MyEventLinkWrapper)`