updated doc strings

Author: Pager07

pages/contractor-skills/contractor-skills-object.yml

@@ -31,7 +31,7 @@ attributes:
   -
     name: subject
     type: object
-    description: The subject/skill details.
+    description: The subject details.
     children:
       -
         name: id
@@ -52,7 +52,7 @@ attributes:
       -
         name: custom_to_branch
         type: bool
-        description: Indicates whether the Subject is custom to a specific branch (True) or not (null).
+        description: Indicates whether the Subject is custom to the API key's Branch (True), or shared across all Branches (null).
   -
     name: qual_level
     type: object
@@ -73,4 +73,4 @@ attributes:
       -
         name: custom_to_branch
         type: bool
-        description: Indicates whether the Qualification Level is custom to a specific branch (True) or not (null).
+        description: Indicates whether the Qualification Level is custom to the API key's Branch (True), or shared across all Branches (null).

pages/contractor-skills/contractor-skills.yml

@@ -24,16 +24,16 @@ sections:
     response: /contractor-skills/get-a-contractor-skill.json
   -
     title: Create a Contractor Skill
-    id: skill-add-to-a-contractor
-    description: /contractor-skills/skill-add-to-a-contractor.md
-    code: /contractor-skills/skill-add-to-a-contractor.py
+    id: create-a-contractor-skills
+    description: /contractor-skills/create-a-contractor-skill.md
+    code: /contractor-skills/create-a-contractor-skill.py
     code_type: POST
     code_url: /api/contractor-skills/
-    response: /contractor-skills/skill-add-to-a-contractor.json
+    response: /contractor-skills/create-a-contractor-skill.json
   -
     title: Delete a Contractor Skill
     id: delete-a-contractor-skill
     description: /contractor-skills/delete-a-contractor-skill.md
     code: /contractor-skills/delete-a-contractor-skill.py
     code_type: DELETE
-    code_url: /api/contractor-skills/<id>/ 
+    code_url: /api/contractor-skills/<id>/

pages/contractor-skills/create-a-contractor-skill.json

@@ -0,0 +1,23 @@
+{
+    "id": 135,
+    "contractor": {
+        "id": 69,
+        "first_name": "Billy",
+        "last_name": "Holiday",
+        "email": null,
+        "url": "http://localhost:8000/api/contractors/69/"
+    },
+    "subject": {
+        "id": 51,
+        "name": "Religious Studies",
+        "category_id": 8,
+        "category_name": "Humanities",
+        "custom_to_branch": null
+    },
+    "qual_level": {
+        "id": 13,
+        "name": "Key Stage 5",
+        "ranking": 35.0,
+        "custom_to_branch": null
+    }
+}

pages/contractor-skills/create-a-contractor-skill.md

@@ -0,0 +1,3 @@
+### Add a Contractor Skill
+
+Creates a new Contractor Skill, representing a relationship between a Contractor and a combination of [Subject](#subjects) and [Qualification Level](#qual-levels). You need to provide the `contractor`, `subject`, and `qual_level` IDs in the request body. Subjects or Qualification Levels custom to another branch, hidden for the branch, or added specifically by the Contractor cannot be used. For more information about what “custom to branch” means, see [Subject](#subjects) and [Qualification Level](#qual-levels).

pages/contractor-skills/create-a-contractor-skill.py

@@ -0,0 +1,5 @@
+import pprint, requests
+data = {"contractor": 69,"subject": 51,"qual_level": 13}
+headers = {'Authorization': 'token <API KEY>'}
+r = requests.post('https://secure.tutorcruncher.com/api/contractor-skills/',json=data, headers=headers)
+pprint.pprint(r.json())

pages/contractor-skills/delete-a-contractor-skill.md

@@ -1,7 +1,3 @@
 ### Delete a Contractor Skill
 
-Deletes an existing Contractor Skill. You only need to specify the unique `id` of the Contractor Skill.
-
-If the specified Contractor Skill ID does not exist, a 404 response will be returned.
-
-A successful deletion returns a 204 response with no content. 
+Deletes a Contractor Skill using its unique ID. Only Contractor Skills associated with the API key's Branch can be deleted. Attempts to delete a skill that belongs to a different Branch or references a Subject or Qualification Level hidden or restricted for the Branch will result in a `400 Bad Request` response. For more information about Branch-specific restrictions, see [Subject](#subjects) and [Qualification Level](#qual-levels).

pages/contractor-skills/get-a-contractor-skill.md

@@ -1,5 +1,4 @@
 ### Get a Contractor Skill
 
 Returns the details of an existing Contractor Skill. You only need to specify the unique `id` of the Contractor Skill to get the correct details.
-
-The response includes the full Contractor Skill object including the Contractor details, [Subject](#subjects) and [Qualification Level](#qual-level). 
+The response includes the full Contractor Skill object including the Contractor details, [Subject](#subjects) and [Qualification Level](#qual-level). 

pages/contractor-skills/list-all-contractor-skills.md

@@ -1,5 +1,3 @@
 ### List all Contractor Skills
+Returns a list of Contractor Skills, each representing a relationship between a Contractor and a combination of [Subject](#subjects) and [Qualification Level](#qual-levels). The results include only skills that are custom to the API key's Branch, exclude skills with hidden Subjects or Qualification Levels for the Branch, and include skills specifically added by the Contractor. If no skills match the filtering criteria, the response will return an empty results array. For more information about what "custom to branch" means, see [Subject](#subjects) and [Qualification Level](#qual-levels).
 
-Returns a list of Contractor Skills. Each Contractor Skill represents a relationship between a Contractor and a combination of [Subject](#subjects) and [Qualification Level](#qual-levels).
-
-The response includes the full details of each Contractor Skill including Contractor information, Subject details, and Qualification Level data.