Merge branch 'develop' of mowoe.com:reverend/lostplaces-backend into develop

django_lostplaces/docs/developer.md

@@ -1,7 +1,7 @@
 # django lostplaces documentation for developer
 
 Greetings,
-this documentation is for anyone who wants to work with this projects codebase or is just curious about our project.
+this documentation is for anyone who wants to work with this projects codebase or is just curious about how it works.
 
 
 ## Models
@@ -9,32 +9,41 @@ The models contain an custom user profile, some abstract base models and the mod
 
 
 ### Explorer user profile
-The class `lostplaces.models.Explorer` is our custom user profile. It has an ForeignKey pointing at django's default user model instead of providing an entire custom user model. That way this django app does not conflict with any other app that has to bring it's own user model.
+Location: `lostplaces.models.models.Explorer`  
+Import from: `lostplaces.models.Explorer`
+#### Super Classes
+- django's `models.Model`
+
+The class `lostplaces.models.Explorer` is our custom user profile. It has an ForeignKey pointing at django's default user model instead of providing an entire custom user model. That way this django app does not conflict with any other app that brings it's own user model.
 
 You can access the explorer profile by accessing the 'explorer' attribute of any user instance
 ```python
 user.explorer
 ```
 
-Currently the explorer profile is used by the abstract model 'Submittable' and thus referenced by 'Place' and 'PlaceImage'. The explorer profile therefore has two attributes
+Currently the explorer profile is used by the abstract model 'Submittable' and has the following realated names/fiels:
-```python
+- [places](###place) A list containing all (lost) places the user has submitted  
-user.explorer.places
+- [placeimages](###placeimages) A list containing all images relating a place that a user has submitted
-user.explorer.placeimages
+- [photoalbums](###photoalbums) A list of all photo albums a explorere has submitted
-```
-`places`  
-A list containing all (lost) places the user has submitted  
-`placeimages`  
-A list containing all images relating a place that a user has submitted
 
 
 ### Taggable
+Location: `lostplaces.models.abstract_models.Taggable`  
+Import from: `lostplaces.models.Taggable`
+#### Super Classes
+- django's `models.Model`
+
 The abstract model Taggable represents an model that is taggable. It depends on the django app [taggit](https://github.com/jazzband/django-taggit). It only consists of one field:  
-`tag`  
+- `tag`: TaggableManager, allows the sub class to be tagged, blank=True allows the admin form to be submitted without any tags
-TaggableManager, allows the sub class to be tagged, blank=True allows the admin form to be submitted without any tags
 
 
 ### Mapable
-The abstract model Mapable represents an model that can be displayed on a map. It consists of tree members  
+Location: `lostplaces.models.abstract_models.Mapable`  
+Import from: `lostplaces.models.Mapable`
+#### Super Classes
+- django's `models.Model`
+
+The abstract model Mapable represents an model that can be displayed on a map. It consists of tree attributes  
 `name`  
 Name of the object, displayed on the map, max length 50 characters  
 `latitude`  
@@ -45,14 +54,36 @@ A mapable model has to provide its own get_absolute_url, in order to provide a l
 
 
 ### Submittable
+Location: `lostplaces.models.abstract_models.Submittable`  
+Import from: `lostplaces.models.Submittable`
+#### Super Classes
+- django's `models.Model`
+
 The abstract model Submittable represents an model that can be submitted by an user. It knows who submitted something and when:  
 `submitted_by`  
 Referencing the explorer profile, see [Explorer](##explorer-user-profile). If the explorer profile is deleted, this instance is kept (on_delete=models.SET_NULL). The related_name is set to the class name, lower case appending an s (%(class)ss)  
 `submitted_when`  
 When the object was submitted, automatically set by django (auto_now_add=True)
 
+### Expireable
+Location: `lostplaces.models.abstract_models.Expireable`  
+Import from: `lostplaces.models.Expireable`
+#### Super Classes
+- django's `models.Model`
+
+This abstract model represents an object that can expire. It is currently used by the Voucher model. I consists of two fields:
+`created_when`  
+The date the object was created, automatically set by django (auto_now_add=True)  
+`expires_when`  
+The date the object expires.
 
 ### Voucher
+Locatoin: `lostplaces.models.Voucher`  
+Import from: `lostplaces.models.Voucher`
+#### Super Classes
+- django's `models.Model`
+- [lostplaces.models.Expireable](###expireable)
+
 A voucher code is needed to sign up using lostplaces sign up form. The model contains  
 `code`  
 The voucher code, max length 30 characters
@@ -63,6 +94,14 @@ Till what date the voucher remains valid
 
 
 ### Place
+Location: `lostplaces.models.place.Place`  
+Import from: `lostplaces.models.Place`
+#### Super Classes
+- django's `models.Model`
+- [lostplaces.models.Submittable](###submittable)-
+- [lostplaces.models.Taggable](###taggable)
+- [lostlaces.models.Mapable]
+
 The place model is the heart of this project. It stores all information about a place needed.  
 `location`  
 Human readable location description (town, village, street), max length 50 characters  
@@ -72,4 +111,45 @@ The place model uses these abstract super classes
 - Submittable, see [Submittable](##submittable) for additional fields
 - Taggable, see [Taggable](##taggable) for additional fields
 - Mapable, see [Mapable](##mapable) for additional fields
-The average_latlon function takes a list of places and returns the center point of all these places
+The average_latlon function takes a list of places and returns the center point of all these places.
+
+### PlaceAsset
+Location: `lostplaces.models.PlaceAsset`  
+Import from: `lostplaces.models.place.PlaceAsset`
+#### Super Classes
+- django's `models.Model`
+- [lostplaces.models.Submittable](###submittable)
+
+A PlaceAsset is anything that belongs to a place. The PlaceImage model for exmpaple is a subclass of PlaceAsset. A PlaceAsset is supposed to be submittable by every user. Only the user who has submitted the asset, the place the asset belongs to or both can delete a asset.
+
+An PlaceAsset has the following fields
+`place`  
+The Place this PlaceAsset belongs to
+
+The PlaceAsset model is a subclass of Submittable, see [Submittable](###submittable) for more details.
+
+### External Link
+Loacation: `lostplaces.models.external_link.ExternalLink`  
+Import From: `lostplaces.models.ExternalLink`
+#### Super Classes
+- django's `models.Model`
+- [lostplaces.models.Submittable](###submittable)
+- [lostplaces.models.PlaceAsset](###placeasset)
+
+This model represents an URL to an external website. External Link is an PlaceAsset, see [above](###placeasset) for more details. External Link has to fields
+`url`  
+the URL to the target
+`label`  
+the label that is shown on the website
+
+### PhotoAlbum
+Loacation: `lostplaces.models.external_link.PhototAlbum`  
+Import From: `lostplaces.models.PhotoAlbum`
+#### Super Classes
+- django's `models.Model`
+- [lostplaces.models.Submittable](###submittable)
+- [lostplaces.models.PlaceAsset](###placeasset)
+- [lostplaces.models.ExternalLink](###externallink)
+
+A photo album is a link to an external site that is meant to contain photos of the place it is referenced in. It 
+does not have any fields, just the ones inherited from it's super class [ExternalLink](###externallink).