From 83e556ba1e129fac28a74b0a2784e4728f491a41 Mon Sep 17 00:00:00 2001 From: Marc Date: Tue, 25 Nov 2014 12:37:20 +0100 Subject: [PATCH 01/47] Missing quotes on validate_score example --- docs/topics/3.0-announcement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/3.0-announcement.md b/docs/topics/3.0-announcement.md index 694ad8a5c..6a662326b 100644 --- a/docs/topics/3.0-announcement.md +++ b/docs/topics/3.0-announcement.md @@ -170,7 +170,7 @@ We strongly recommend that you use the namespaced import style of `import serial The `validate_` method hooks that can be attached to serializer classes change their signature slightly and return type. Previously these would take a dictionary of all incoming data, and a key representing the field name, and would return a dictionary including the validated data for that field: def validate_score(self, attrs, source): - if attrs[score] % 10 != 0: + if attrs['score'] % 10 != 0: raise serializers.ValidationError('This field should be a multiple of ten.') return attrs From 3a648b9f0b0aa9a955065b96ea1a03376816ec00 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Thu, 9 Oct 2014 10:14:04 +0100 Subject: [PATCH 02/47] Migrate documentation to MkDocs proper --- .gitignore | 1 + docs/{ => theme}/404.html | 0 docs/{template.html => theme/base.html} | 7 +- mkdocs.py | 203 ------------------------ mkdocs.yml | 55 +++++++ 5 files changed, 62 insertions(+), 204 deletions(-) rename docs/{ => theme}/404.html (100%) rename docs/{template.html => theme/base.html} (96%) delete mode 100755 mkdocs.py create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore index ae73f8379..9e17827bd 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,4 @@ local/ !.gitignore !.travis.yml +site/ diff --git a/docs/404.html b/docs/theme/404.html similarity index 100% rename from docs/404.html rename to docs/theme/404.html diff --git a/docs/template.html b/docs/theme/base.html similarity index 96% rename from docs/template.html rename to docs/theme/base.html index f36cffc6d..45e19cf37 100644 --- a/docs/template.html +++ b/docs/theme/base.html @@ -187,7 +187,12 @@ a.fusion-poweredby { -->
    - {{ toc }} + {% for toc_item in toc %} +
  • {{ toc_item.title }}
    • + {% for toc_item in toc_item.children %} +
  • {{ toc_item.title }}
    • + {% endfor %} + {% endfor %}
    {{ ad_block }}
    diff --git a/mkdocs.py b/mkdocs.py deleted file mode 100755 index 3787d7920..000000000 --- a/mkdocs.py +++ /dev/null @@ -1,203 +0,0 @@ -#!/usr/bin/env python - -import markdown -import os -import re -import shutil -import sys - -root_dir = os.path.abspath(os.path.dirname(__file__)) -docs_dir = os.path.join(root_dir, 'docs') -html_dir = os.path.join(root_dir, 'html') - -local = not '--deploy' in sys.argv -preview = '-p' in sys.argv - -if local: - base_url = 'file://%s/' % os.path.normpath(os.path.join(os.getcwd(), html_dir)) - suffix = '.html' - index = 'index.html' -else: - base_url = 'http://www.django-rest-framework.org' - suffix = '' - index = '' - - -main_header = '
  • {{ title }}
    • ' -sub_header = '
  • {{ title }}
    • ' -code_label = r'\1' - -page = open(os.path.join(docs_dir, 'template.html'), 'r').read() - -# Copy static files -# for static in ['css', 'js', 'img']: -# source = os.path.join(docs_dir, 'static', static) -# target = os.path.join(html_dir, static) -# if os.path.exists(target): -# shutil.rmtree(target) -# shutil.copytree(source, target) - - -# Hacky, but what the hell, it'll do the job -path_list = [ - 'index.md', - 'tutorial/quickstart.md', - 'tutorial/1-serialization.md', - 'tutorial/2-requests-and-responses.md', - 'tutorial/3-class-based-views.md', - 'tutorial/4-authentication-and-permissions.md', - 'tutorial/5-relationships-and-hyperlinked-apis.md', - 'tutorial/6-viewsets-and-routers.md', - 'api-guide/requests.md', - 'api-guide/responses.md', - 'api-guide/views.md', - 'api-guide/generic-views.md', - 'api-guide/viewsets.md', - 'api-guide/routers.md', - 'api-guide/parsers.md', - 'api-guide/renderers.md', - 'api-guide/serializers.md', - 'api-guide/fields.md', - 'api-guide/relations.md', - 'api-guide/validators.md', - 'api-guide/authentication.md', - 'api-guide/permissions.md', - 'api-guide/throttling.md', - 'api-guide/filtering.md', - 'api-guide/pagination.md', - 'api-guide/content-negotiation.md', - 'api-guide/format-suffixes.md', - 'api-guide/reverse.md', - 'api-guide/exceptions.md', - 'api-guide/status-codes.md', - 'api-guide/testing.md', - 'api-guide/settings.md', - 'topics/documenting-your-api.md', - 'topics/ajax-csrf-cors.md', - 'topics/browser-enhancements.md', - 'topics/browsable-api.md', - 'topics/rest-hypermedia-hateoas.md', - 'topics/third-party-resources.md', - 'topics/contributing.md', - 'topics/rest-framework-2-announcement.md', - 'topics/2.2-announcement.md', - 'topics/2.3-announcement.md', - 'topics/2.4-announcement.md', - 'topics/release-notes.md', - 'topics/credits.md', -] - -prev_url_map = {} -next_url_map = {} -for idx in range(len(path_list)): - path = path_list[idx] - rel = '../' * path.count('/') - - if idx == 1 and not local: - # Link back to '/', not '/index' - prev_url_map[path] = '/' - elif idx > 0: - prev_url_map[path] = rel + path_list[idx - 1][:-3] + suffix - - if idx < len(path_list) - 1: - next_url_map[path] = rel + path_list[idx + 1][:-3] + suffix - - -for (dirpath, dirnames, filenames) in os.walk(docs_dir): - relative_dir = dirpath.replace(docs_dir, '').lstrip(os.path.sep) - build_dir = os.path.join(html_dir, relative_dir) - - if not os.path.exists(build_dir): - os.makedirs(build_dir) - - for filename in filenames: - path = os.path.join(dirpath, filename) - relative_path = os.path.join(relative_dir, filename) - - if not filename.endswith('.md'): - if relative_dir: - output_path = os.path.join(build_dir, filename) - shutil.copy(path, output_path) - continue - - output_path = os.path.join(build_dir, filename[:-3] + '.html') - - toc = '' - text = open(path, 'r').read().decode('utf-8') - main_title = None - description = 'Django, API, REST' - for line in text.splitlines(): - if line.startswith('# '): - title = line[2:].strip() - template = main_header - description = description + ', ' + title - elif line.startswith('## '): - title = line[3:].strip() - template = sub_header - else: - continue - - if not main_title: - main_title = title - anchor = title.lower().replace(' ', '-').replace(':-', '-').replace("'", '').replace('?', '').replace('.', '') - template = template.replace('{{ title }}', title) - template = template.replace('{{ anchor }}', anchor) - toc += template + '\n' - - if filename == 'index.md': - main_title = 'Django REST framework - Web APIs for Django' - else: - main_title = main_title + ' - Django REST framework' - - if relative_path == 'index.md': - canonical_url = base_url - else: - canonical_url = base_url + '/' + relative_path[:-3] + suffix - prev_url = prev_url_map.get(relative_path) - next_url = next_url_map.get(relative_path) - - content = markdown.markdown(text, ['headerid']) - - output = page.replace('{{ content }}', content).replace('{{ toc }}', toc).replace('{{ base_url }}', base_url).replace('{{ suffix }}', suffix).replace('{{ index }}', index) - output = output.replace('{{ title }}', main_title) - output = output.replace('{{ description }}', description) - output = output.replace('{{ page_id }}', filename[:-3]) - output = output.replace('{{ canonical_url }}', canonical_url) - - if filename =='index.md': - output = output.replace('{{ ad_block }}', """
    - """) - else: - output = output.replace('{{ ad_block }}', '') - - if prev_url: - output = output.replace('{{ prev_url }}', prev_url) - output = output.replace('{{ prev_url_disabled }}', '') - else: - output = output.replace('{{ prev_url }}', '#') - output = output.replace('{{ prev_url_disabled }}', 'disabled') - - if next_url: - output = output.replace('{{ next_url }}', next_url) - output = output.replace('{{ next_url_disabled }}', '') - else: - output = output.replace('{{ next_url }}', '#') - output = output.replace('{{ next_url_disabled }}', 'disabled') - - output = re.sub(r'a href="([^"]*)\.md"', r'a href="\1%s"' % suffix, output) - output = re.sub(r'
    :::bash', r'
    ', output)
-        output = re.sub(r'
    ', r'
    ', output)
-        output = re.sub(r'', code_label, output)
-        open(output_path, 'w').write(output.encode('utf-8'))
-
-if preview:
-    import subprocess
-
-    url = 'html/index.html'
-
-    try:
-        subprocess.Popen(["open", url])  # Mac
-    except OSError:
-        subprocess.Popen(["xdg-open", url])  # Linux
-    except:
-        os.startfile(url)  # Windows
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 000000000..0134679c4
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,55 @@
+site_name: Django REST frameowkr
+site_url: http://www.django-rest-framework.org/
+site_description: Django REST framework - Web APIs for DjangoProject documentation with Markdown.
+
+repo_url: https://github.com/tomchristie/django-rest-framework
+
+pages:
+ - ['index.md', ]
+ - ['tutorial/quickstart.md', ]
+ - ['tutorial/1-serialization.md', ]
+ - ['tutorial/2-requests-and-responses.md', ]
+ - ['tutorial/3-class-based-views.md', ]
+ - ['tutorial/4-authentication-and-permissions.md', ]
+ - ['tutorial/5-relationships-and-hyperlinked-apis.md', ]
+ - ['tutorial/6-viewsets-and-routers.md', ]
+ - ['api-guide/requests.md', ]
+ - ['api-guide/responses.md', ]
+ - ['api-guide/views.md', ]
+ - ['api-guide/generic-views.md', ]
+ - ['api-guide/viewsets.md', ]
+ - ['api-guide/routers.md', ]
+ - ['api-guide/parsers.md', ]
+ - ['api-guide/renderers.md', ]
+ - ['api-guide/serializers.md', ]
+ - ['api-guide/fields.md', ]
+ - ['api-guide/relations.md', ]
+ - ['api-guide/authentication.md', ]
+ - ['api-guide/permissions.md', ]
+ - ['api-guide/throttling.md', ]
+ - ['api-guide/filtering.md', ]
+ - ['api-guide/pagination.md', ]
+ - ['api-guide/content-negotiation.md', ]
+ - ['api-guide/format-suffixes.md', ]
+ - ['api-guide/reverse.md', ]
+ - ['api-guide/exceptions.md', ]
+ - ['api-guide/status-codes.md', ]
+ - ['api-guide/testing.md', ]
+ - ['api-guide/settings.md', ]
+ - ['topics/documenting-your-api.md', ]
+ - ['topics/ajax-csrf-cors.md', ]
+ - ['topics/browser-enhancements.md', ]
+ - ['topics/browsable-api.md', ]
+ - ['topics/rest-hypermedia-hateoas.md', ]
+ - ['topics/third-party-resources.md', ]
+ - ['topics/contributing.md', ]
+ - ['topics/rest-framework-2-announcement.md', ]
+ - ['topics/2.2-announcement.md', ]
+ - ['topics/2.3-announcement.md', ]
+ - ['topics/2.4-announcement.md', ]
+ - ['topics/release-notes.md', ]
+ - ['topics/credits.md', ]
+
+theme_dir: docs/theme
+copyright: Copyright © 2014, Tom Christie.
+google_analytics: ['UA-27795084-5', 'mkdocs.org']

From b2762cbb76a2602361fe5a9af6804863127d1c67 Mon Sep 17 00:00:00 2001
From: Dougal Matthews 
Date: Wed, 22 Oct 2014 21:13:08 +0100
Subject: [PATCH 03/47] Fixed typos in the config and updated Google analytics

---
 .gitignore | 1 +
 mkdocs.yml | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index 9e17827bd..2341eba0d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,4 +18,5 @@ local/
 
 !.gitignore
 !.travis.yml
+
 site/
diff --git a/mkdocs.yml b/mkdocs.yml
index 0134679c4..8db4efc16 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,4 +1,4 @@
-site_name: Django REST frameowkr
+site_name: Django REST framework
 site_url: http://www.django-rest-framework.org/
 site_description: Django REST framework - Web APIs for DjangoProject documentation with Markdown.
 
@@ -52,4 +52,4 @@ pages:
 
 theme_dir: docs/theme
 copyright: Copyright © 2014, Tom Christie.
-google_analytics: ['UA-27795084-5', 'mkdocs.org']
+google_analytics: ['UA-18852272-2', 'django-rest-framework.org']

From 261c4ce9aff6725a4e069cf45d0f57ec97a27bdb Mon Sep 17 00:00:00 2001
From: Dougal Matthews 
Date: Wed, 22 Oct 2014 21:13:40 +0100
Subject: [PATCH 04/47] Remove redundant requirements file

---
 docs/requirements.txt | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 docs/requirements.txt

diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index a91fb9785..000000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1 +0,0 @@
-markdown>=2.1.0

From ae36a258d7266f73b73a0a722d39ff806d552e1b Mon Sep 17 00:00:00 2001
From: Dougal Matthews 
Date: Wed, 22 Oct 2014 21:21:59 +0100
Subject: [PATCH 05/47] Add the kickstarter annoucement to the TOC

---
 mkdocs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/mkdocs.yml b/mkdocs.yml
index 8db4efc16..cfaaed420 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -47,6 +47,7 @@ pages:
  - ['topics/2.2-announcement.md', ]
  - ['topics/2.3-announcement.md', ]
  - ['topics/2.4-announcement.md', ]
+ - ['topics/kickstarter-announcement.md', ]
  - ['topics/release-notes.md', ]
  - ['topics/credits.md', ]
 

From 04abe9830c1b6c0670a49129529e8e8d9e411f2c Mon Sep 17 00:00:00 2001
From: Dougal Matthews 
Date: Wed, 22 Oct 2014 21:22:16 +0100
Subject: [PATCH 06/47] Add a docs build to the Tox run

---
 .travis.yml | 1 +
 tox.ini     | 5 +++++
 2 files changed, 6 insertions(+)

diff --git a/.travis.yml b/.travis.yml
index 9dd587be9..6191e7e26 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -4,6 +4,7 @@ sudo: false
 
 env:
     - TOX_ENV=py27-flake8
+    - TOX_ENV=py27-docs
     - TOX_ENV=py34-django17
     - TOX_ENV=py33-django17
     - TOX_ENV=py32-django17
diff --git a/tox.ini b/tox.ini
index a7200a3f3..6b680813d 100644
--- a/tox.ini
+++ b/tox.ini
@@ -29,3 +29,8 @@ deps =
        pytest==2.5.2
        flake8==2.2.2
 commands = ./runtests.py --lintonly
+
+[testenv:py27-docs]
+deps =
+       mkdocs>=0.11.1
+commands = mkdocs build

From 84d9c4b46eacda54b31a3779c623554758f4dccc Mon Sep 17 00:00:00 2001
From: Dougal Matthews 
Date: Wed, 22 Oct 2014 21:36:11 +0100
Subject: [PATCH 07/47] Change site_dir to html to match mkdocs.py

---
 CONTRIBUTING.md             | 8 ++++----
 docs/topics/contributing.md | 8 ++++----
 mkdocs.yml                  | 1 +
 3 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1b1995348..ff82c9545 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -101,15 +101,15 @@ There are many great markdown editors that make working with the documentation r
 
 ## Building the documentation
 
-To build the documentation, simply run the `mkdocs.py` script.
+To build the documentation, simply install MkDocs with `pip install mkdocs` and then run the following command.
 
-    ./mkdocs.py
+    mkdocs build
 
 This will build the html output into the `html` directory.
 
-You can build the documentation and open a preview in a browser window by using the `-p` flag.
+You can build the documentation and open a preview in a browser window by using the `serve` command.
 
-    ./mkdocs.py -p
+    mkdocs serve
 
 ## Language style
 
diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md
index 52f6e287d..5809af65c 100644
--- a/docs/topics/contributing.md
+++ b/docs/topics/contributing.md
@@ -135,15 +135,15 @@ There are many great Markdown editors that make working with the documentation r
 
 ## Building the documentation
 
-To build the documentation, simply run the `mkdocs.py` script.
+To build the documentation, simply install MkDocs with `pip install mkdocs` and then run the following command.
 
-    ./mkdocs.py
+    mkdocs build
 
 This will build the html output into the `html` directory.
 
-You can build the documentation and open a preview in a browser window by using the `-p` flag.
+You can build the documentation and open a preview in a browser window by using the `serve` command.
 
-    ./mkdocs.py -p
+    mkdocs serve
 
 ## Language style
 
diff --git a/mkdocs.yml b/mkdocs.yml
index cfaaed420..e2c3abe8c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -51,6 +51,7 @@ pages:
  - ['topics/release-notes.md', ]
  - ['topics/credits.md', ]
 
+site_dir: html
 theme_dir: docs/theme
 copyright: Copyright © 2014, Tom Christie.
 google_analytics: ['UA-18852272-2', 'django-rest-framework.org']

From 792c0c291f2cbe3c51de9e43cfee35c121e13687 Mon Sep 17 00:00:00 2001
From: Dougal Matthews 
Date: Thu, 23 Oct 2014 08:11:24 +0100
Subject: [PATCH 08/47] Remove the site ignore which isn't needed as we will
 use the html output directory as before

---
 .gitignore | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index 2341eba0d..ae73f8379 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,5 +18,3 @@ local/
 
 !.gitignore
 !.travis.yml
-
-site/

From 2ddef2d3263b2187fd502e42eaaecc3a4f0ad2b2 Mon Sep 17 00:00:00 2001
From: Dougal Matthews 
Date: Thu, 23 Oct 2014 14:10:23 +0100
Subject: [PATCH 09/47] Drop simply from the mkdocs install lines

It is still simple tho', honest ;)
---
 CONTRIBUTING.md             | 2 +-
 docs/topics/contributing.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ff82c9545..698029959 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -101,7 +101,7 @@ There are many great markdown editors that make working with the documentation r
 
 ## Building the documentation
 
-To build the documentation, simply install MkDocs with `pip install mkdocs` and then run the following command.
+To build the documentation, install MkDocs with `pip install mkdocs` and then run the following command.
 
     mkdocs build
 
diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md
index 5809af65c..c7991a0fe 100644
--- a/docs/topics/contributing.md
+++ b/docs/topics/contributing.md
@@ -135,7 +135,7 @@ There are many great Markdown editors that make working with the documentation r
 
 ## Building the documentation
 
-To build the documentation, simply install MkDocs with `pip install mkdocs` and then run the following command.
+To build the documentation, install MkDocs with `pip install mkdocs` and then run the following command.
 
     mkdocs build
 

From d6b203f013890cc25f5454696805bc85c1ca2482 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Padilla?= 
Date: Tue, 28 Oct 2014 17:40:29 -0400
Subject: [PATCH 10/47] Use page_title instead of title in docs theme

---
 docs/theme/base.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/theme/base.html b/docs/theme/base.html
index 45e19cf37..943a60e4c 100644
--- a/docs/theme/base.html
+++ b/docs/theme/base.html
@@ -2,7 +2,7 @@
 
 
     
-    {{ title }}
+    {{ page_title }}
     
     
     

From 18712a5cbcbb25d935b93baac589cacfe1cbb754 Mon Sep 17 00:00:00 2001
From: Dougal Matthews 
Date: Wed, 29 Oct 2014 20:54:20 +0000
Subject: [PATCH 11/47] Fix the Navigation style

---
 docs/theme/base.html | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/docs/theme/base.html b/docs/theme/base.html
index 943a60e4c..e5ad43777 100644
--- a/docs/theme/base.html
+++ b/docs/theme/base.html
@@ -188,15 +188,12 @@ a.fusion-poweredby {
             
    
               
+
From 49a493f61f4d5b4447d139d189d78995e65231b2 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 29 Oct 2014 20:54:31 +0000 Subject: [PATCH 12/47] Bring back the promo section --- docs/theme/base.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/theme/base.html b/docs/theme/base.html index e5ad43777..7ca7de145 100644 --- a/docs/theme/base.html +++ b/docs/theme/base.html @@ -191,7 +191,8 @@ a.fusion-poweredby {
  • {{ toc_item.title }}
    • {% endfor %}
    - {{ ad_block }} +
    +
    From 3c49b9fe4648d6fb291f0d34bf2e9ef4b72d45be Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 29 Oct 2014 21:03:00 +0000 Subject: [PATCH 13/47] Add next and previous page. --- docs/theme/base.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/theme/base.html b/docs/theme/base.html index 7ca7de145..0f876cc16 100644 --- a/docs/theme/base.html +++ b/docs/theme/base.html @@ -57,8 +57,8 @@ a.fusion-poweredby {
    GitHub - Next - Previous + Next + Previous Search From 5600878672a47a6aedd49322b4e0c9cce561d1d6 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 29 Oct 2014 21:26:23 +0000 Subject: [PATCH 14/47] Fixed the TOC (again) Not sure how I broke it ;-) --- docs/theme/base.html | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/theme/base.html b/docs/theme/base.html index 0f876cc16..bb3ede2a2 100644 --- a/docs/theme/base.html +++ b/docs/theme/base.html @@ -189,11 +189,10 @@ a.fusion-poweredby {
    From 6da9d5aee09aecbfb7afdacdd2e445e7c30c5999 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 29 Oct 2014 21:26:51 +0000 Subject: [PATCH 15/47] Add a workaround for not having the index name --- docs/theme/base.html | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/theme/base.html b/docs/theme/base.html index bb3ede2a2..d8ff0e072 100644 --- a/docs/theme/base.html +++ b/docs/theme/base.html @@ -49,7 +49,8 @@ a.fusion-poweredby { } - + {# TODO: This is a bit of a hack. We don't want to refer to the file specifically. #} +
    @@ -193,6 +194,15 @@ a.fusion-poweredby {
  • {{ toc_item.title }}
    • {% endfor %} {% endfor %} + + {# TODO: This is a bit of a hack. We don't want to refer to the file specifically. #} + {% if current_page.input_path == 'index.md' %} +
    +
    + +
    + {% endif %} +
    From b443f81481815423d0f953ca41052b4993dfb12f Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 29 Oct 2014 22:29:11 +0000 Subject: [PATCH 16/47] Add meta description --- docs/theme/base.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/theme/base.html b/docs/theme/base.html index d8ff0e072..5187d581a 100644 --- a/docs/theme/base.html +++ b/docs/theme/base.html @@ -6,7 +6,7 @@ - + From 5d479c20d8b9a376057517a4d53d58ff891f5483 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 29 Oct 2014 22:29:41 +0000 Subject: [PATCH 17/47] Move nav to it's own template based on the MkDocs theme --- docs/theme/base.html | 93 +------------------------------------------- docs/theme/nav.html | 45 +++++++++++++++++++++ 2 files changed, 46 insertions(+), 92 deletions(-) create mode 100644 docs/theme/nav.html diff --git a/docs/theme/base.html b/docs/theme/base.html index 5187d581a..4ca6cd810 100644 --- a/docs/theme/base.html +++ b/docs/theme/base.html @@ -54,98 +54,7 @@ a.fusion-poweredby {
    -
    -
    -
    - GitHub - Next - Previous - Search - - - - - - Django REST framework -
    - -
      - -
    -
    -
    -
    -
    + {% include "nav.html" %}
    diff --git a/docs/theme/nav.html b/docs/theme/nav.html new file mode 100644 index 000000000..a7a72d68e --- /dev/null +++ b/docs/theme/nav.html @@ -0,0 +1,45 @@ + +
    +
    +
    + GitHub + Next + Previous + Search + + + + + + Django REST framework +
    + {% if include_nav %} + + + {% endif %} +
    + +
    +
    +
    From 6a10b90f72e2f36b1eae1da649eba758b1377be3 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 29 Oct 2014 22:30:00 +0000 Subject: [PATCH 18/47] Correct the capitalisation of API --- mkdocs.yml | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index e2c3abe8c..de4b9922c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,29 +13,29 @@ pages: - ['tutorial/4-authentication-and-permissions.md', ] - ['tutorial/5-relationships-and-hyperlinked-apis.md', ] - ['tutorial/6-viewsets-and-routers.md', ] - - ['api-guide/requests.md', ] - - ['api-guide/responses.md', ] - - ['api-guide/views.md', ] - - ['api-guide/generic-views.md', ] - - ['api-guide/viewsets.md', ] - - ['api-guide/routers.md', ] - - ['api-guide/parsers.md', ] - - ['api-guide/renderers.md', ] - - ['api-guide/serializers.md', ] - - ['api-guide/fields.md', ] - - ['api-guide/relations.md', ] - - ['api-guide/authentication.md', ] - - ['api-guide/permissions.md', ] - - ['api-guide/throttling.md', ] - - ['api-guide/filtering.md', ] - - ['api-guide/pagination.md', ] - - ['api-guide/content-negotiation.md', ] - - ['api-guide/format-suffixes.md', ] - - ['api-guide/reverse.md', ] - - ['api-guide/exceptions.md', ] - - ['api-guide/status-codes.md', ] - - ['api-guide/testing.md', ] - - ['api-guide/settings.md', ] + - ['api-guide/requests.md', "API Guide", ] + - ['api-guide/responses.md', "API Guide", ] + - ['api-guide/views.md', "API Guide", ] + - ['api-guide/generic-views.md', "API Guide", ] + - ['api-guide/viewsets.md', "API Guide", ] + - ['api-guide/routers.md', "API Guide", ] + - ['api-guide/parsers.md', "API Guide", ] + - ['api-guide/renderers.md', "API Guide", ] + - ['api-guide/serializers.md', "API Guide", ] + - ['api-guide/fields.md', "API Guide", ] + - ['api-guide/relations.md', "API Guide", ] + - ['api-guide/authentication.md', "API Guide", ] + - ['api-guide/permissions.md', "API Guide", ] + - ['api-guide/throttling.md', "API Guide", ] + - ['api-guide/filtering.md', "API Guide", ] + - ['api-guide/pagination.md', "API Guide", ] + - ['api-guide/content-negotiation.md', "API Guide", ] + - ['api-guide/format-suffixes.md', "API Guide", ] + - ['api-guide/reverse.md', "API Guide", ] + - ['api-guide/exceptions.md', "API Guide", ] + - ['api-guide/status-codes.md', "API Guide", ] + - ['api-guide/testing.md', "API Guide", ] + - ['api-guide/settings.md', "API Guide", ] - ['topics/documenting-your-api.md', ] - ['topics/ajax-csrf-cors.md', ] - ['topics/browser-enhancements.md', ] From d72a56f37f59d0700d163b67d5af78fc545c91f7 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Fri, 31 Oct 2014 15:02:47 +0000 Subject: [PATCH 19/47] Move the docs theme out of the docs folder. --- {docs/theme => docs_theme}/404.html | 0 {docs/theme => docs_theme}/base.html | 0 {docs/theme => docs_theme}/nav.html | 0 mkdocs.yml | 2 +- 4 files changed, 1 insertion(+), 1 deletion(-) rename {docs/theme => docs_theme}/404.html (100%) rename {docs/theme => docs_theme}/base.html (100%) rename {docs/theme => docs_theme}/nav.html (100%) diff --git a/docs/theme/404.html b/docs_theme/404.html similarity index 100% rename from docs/theme/404.html rename to docs_theme/404.html diff --git a/docs/theme/base.html b/docs_theme/base.html similarity index 100% rename from docs/theme/base.html rename to docs_theme/base.html diff --git a/docs/theme/nav.html b/docs_theme/nav.html similarity index 100% rename from docs/theme/nav.html rename to docs_theme/nav.html diff --git a/mkdocs.yml b/mkdocs.yml index de4b9922c..4e5840093 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -52,6 +52,6 @@ pages: - ['topics/credits.md', ] site_dir: html -theme_dir: docs/theme +theme_dir: docs_theme copyright: Copyright © 2014, Tom Christie. google_analytics: ['UA-18852272-2', 'django-rest-framework.org'] From 78223eb8efe2e4e44516edd9a70597b62211df35 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Fri, 31 Oct 2014 15:05:21 +0000 Subject: [PATCH 20/47] Fixed copypasta fail --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 4e5840093..45cbb7e72 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ site_name: Django REST framework site_url: http://www.django-rest-framework.org/ -site_description: Django REST framework - Web APIs for DjangoProject documentation with Markdown. +site_description: Django REST framework - Web APIs for Django repo_url: https://github.com/tomchristie/django-rest-framework From cbb6799d2dc2d87e58e67e1044075319262a674b Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 5 Nov 2014 13:59:45 +0000 Subject: [PATCH 21/47] Add validators from 27622058872c00e357deb7d7e86619a793ef4b41 and 254701230d85612cf0210d4549c2d74f410a181d --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 45cbb7e72..2d1886a05 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,6 +24,7 @@ pages: - ['api-guide/serializers.md', "API Guide", ] - ['api-guide/fields.md', "API Guide", ] - ['api-guide/relations.md', "API Guide", ] + - ['api-guide/validators.md', "API Guide", ] - ['api-guide/authentication.md', "API Guide", ] - ['api-guide/permissions.md', "API Guide", ] - ['api-guide/throttling.md', "API Guide", ] From 16d442dda3ee9d4ff40d067d76706959aac4c6a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jose=CC=81=20Padilla?= Date: Fri, 31 Oct 2014 09:04:39 -0400 Subject: [PATCH 22/47] Use MkDocs meta.source to render source code links --- docs/api-guide/authentication.md | 2 +- docs/api-guide/content-negotiation.md | 6 ++-- docs/api-guide/exceptions.md | 2 +- docs/api-guide/fields.md | 4 +-- docs/api-guide/filtering.md | 24 ++++++++-------- docs/api-guide/format-suffixes.md | 12 ++++---- docs/api-guide/generic-views.md | 4 +-- docs/api-guide/pagination.md | 6 ++-- docs/api-guide/parsers.md | 6 ++-- docs/api-guide/permissions.md | 8 +++--- docs/api-guide/relations.md | 40 +++++++++++++-------------- docs/api-guide/renderers.md | 14 +++++----- docs/api-guide/requests.md | 8 +++--- docs/api-guide/responses.md | 4 +-- docs/api-guide/reverse.md | 4 +-- docs/api-guide/routers.md | 8 +++--- docs/api-guide/serializers.md | 34 +++++++++++------------ docs/api-guide/settings.md | 2 +- docs/api-guide/status-codes.md | 6 ++-- docs/api-guide/testing.md | 6 ++-- docs/api-guide/throttling.md | 10 +++---- docs/api-guide/views.md | 7 +++-- docs/api-guide/viewsets.md | 2 +- docs/theme/content.html | 11 ++++++++ docs_theme/base.html | 2 +- 25 files changed, 122 insertions(+), 110 deletions(-) create mode 100644 docs/theme/content.html diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 01774c10d..b04858e39 100755 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -1,4 +1,4 @@ - +source: authentication.py # Authentication diff --git a/docs/api-guide/content-negotiation.md b/docs/api-guide/content-negotiation.md index 94dd59cac..bc3b09fb7 100644 --- a/docs/api-guide/content-negotiation.md +++ b/docs/api-guide/content-negotiation.md @@ -1,4 +1,4 @@ - +source: negotiation.py # Content negotiation @@ -29,7 +29,7 @@ The priorities for each of the given media types would be: If the requested view was only configured with renderers for `YAML` and `HTML`, then REST framework would select whichever renderer was listed first in the `renderer_classes` list or `DEFAULT_RENDERER_CLASSES` setting. -For more information on the `HTTP Accept` header, see [RFC 2616][accept-header] +For more information on the `HTTP Accept` header, see [RFC 2616][accept-header] --- @@ -62,7 +62,7 @@ request when selecting the appropriate parser or renderer. Select the first parser in the `.parser_classes` list. """ return parsers[0] - + def select_renderer(self, request, renderers, format_suffix): """ Select the first renderer in the `.renderer_classes` list. diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md index e61dcfa90..8e0b1958e 100644 --- a/docs/api-guide/exceptions.md +++ b/docs/api-guide/exceptions.md @@ -1,4 +1,4 @@ - +source: exceptions.py # Exceptions diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 292a51d89..354ec9662 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -1,4 +1,4 @@ - +source: fields.py # Serializer fields @@ -62,7 +62,7 @@ A dictionary of error codes to error messages. ### `widget` Used only if rendering the field to HTML. -This argument sets the widget that should be used to render the field. For more details, and a list of available widgets, see [the Django documentation on form widgets][django-widgets]. +This argument sets the widget that should be used to render the field. For more details, and a list of available widgets, see [the Django documentation on form widgets][django-widgets]. ### `label` diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index cfeb43349..83977048f 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -1,4 +1,4 @@ - +source: filters.py # Filtering @@ -26,7 +26,7 @@ For example: class PurchaseList(generics.ListAPIView): serializer_class = PurchaseSerializer - + def get_queryset(self): """ This view should return a list of all the purchases @@ -38,7 +38,7 @@ For example: ## Filtering against the URL -Another style of filtering might involve restricting the queryset based on some part of the URL. +Another style of filtering might involve restricting the queryset based on some part of the URL. For example if your URL config contained an entry like this: @@ -48,7 +48,7 @@ You could then write a view that returned a purchase queryset filtered by the us class PurchaseList(generics.ListAPIView): serializer_class = PurchaseSerializer - + def get_queryset(self): """ This view should return a list of all the purchases for @@ -57,7 +57,7 @@ You could then write a view that returned a purchase queryset filtered by the us username = self.kwargs['username'] return Purchase.objects.filter(purchaser__username=username) -## Filtering against query parameters +## Filtering against query parameters A final example of filtering the initial queryset would be to determine the initial queryset based on query parameters in the url. @@ -65,7 +65,7 @@ We can override `.get_queryset()` to deal with URLs such as `http://example.com/ class PurchaseList(generics.ListAPIView): serializer_class = PurchaseSerializer - + def get_queryset(self): """ Optionally restricts the returned purchases to a given user, @@ -113,7 +113,7 @@ For instance, given the previous example, and a product with an id of `4675`, th http://example.com/api/products/4675/?category=clothing&max_price=10.00 ## Overriding the initial queryset - + Note that you can use both an overridden `.get_queryset()` and generic filtering together, and everything will work as expected. For example, if `Product` had a many-to-many relationship with `User`, named `purchase`, you might want to write a view like this: class PurchasedProductsList(generics.ListAPIView): @@ -124,7 +124,7 @@ Note that you can use both an overridden `.get_queryset()` and generic filtering model = Product serializer_class = ProductSerializer filter_class = ProductFilter - + def get_queryset(self): user = self.request.user return user.purchase_set.all() @@ -135,7 +135,7 @@ Note that you can use both an overridden `.get_queryset()` and generic filtering ## DjangoFilterBackend -The `DjangoFilterBackend` class supports highly customizable field filtering, using the [django-filter package][django-filter]. +The `DjangoFilterBackend` class supports highly customizable field filtering, using the [django-filter package][django-filter]. To use REST framework's `DjangoFilterBackend`, first install `django-filter`. @@ -216,7 +216,7 @@ This is nice, but it exposes the Django's double underscore convention as part o And now you can execute: http://example.com/api/products?manufacturer=foo - + For more details on using filter sets see the [django-filter documentation][django-filter-docs]. --- @@ -224,7 +224,7 @@ For more details on using filter sets see the [django-filter documentation][djan **Hints & Tips** * By default filtering is not enabled. If you want to use `DjangoFilterBackend` remember to make sure it is installed by using the `'DEFAULT_FILTER_BACKENDS'` setting. -* When using boolean fields, you should use the values `True` and `False` in the URL query parameters, rather than `0`, `1`, `true` or `false`. (The allowed boolean values are currently hardwired in Django's [NullBooleanSelect implementation][nullbooleanselect].) +* When using boolean fields, you should use the values `True` and `False` in the URL query parameters, rather than `0`, `1`, `true` or `false`. (The allowed boolean values are currently hardwired in Django's [NullBooleanSelect implementation][nullbooleanselect].) * `django-filter` supports filtering across relationships, using Django's double-underscore syntax. * For Django 1.3 support, make sure to install `django-filter` version 0.5.4, as later versions drop support for 1.3. @@ -316,7 +316,7 @@ Typically you'd instead control this by setting `order_by` on the initial querys queryset = User.objects.all() serializer_class = UserSerializer filter_backends = (filters.OrderingFilter,) - ordering = ('username',) + ordering = ('username',) The `ordering` attribute may be either a string or a list/tuple of strings. diff --git a/docs/api-guide/format-suffixes.md b/docs/api-guide/format-suffixes.md index 76a3367b0..20c1e9952 100644 --- a/docs/api-guide/format-suffixes.md +++ b/docs/api-guide/format-suffixes.md @@ -1,4 +1,4 @@ - +source: urlpatterns.py # Format suffixes @@ -7,7 +7,7 @@ used all the time. > > — Roy Fielding, [REST discuss mailing list][cite] -A common pattern for Web APIs is to use filename extensions on URLs to provide an endpoint for a given media type. For example, 'http://example.com/api/users.json' to serve a JSON representation. +A common pattern for Web APIs is to use filename extensions on URLs to provide an endpoint for a given media type. For example, 'http://example.com/api/users.json' to serve a JSON representation. Adding format-suffix patterns to each individual entry in the URLconf for your API is error-prone and non-DRY, so REST framework provides a shortcut to adding these patterns to your URLConf. @@ -21,7 +21,7 @@ Arguments: * **urlpatterns**: Required. A URL pattern list. * **suffix_required**: Optional. A boolean indicating if suffixes in the URLs should be optional or mandatory. Defaults to `False`, meaning that suffixes are optional by default. -* **allowed**: Optional. A list or tuple of valid format suffixes. If not provided, a wildcard format suffix pattern will be used. +* **allowed**: Optional. A list or tuple of valid format suffixes. If not provided, a wildcard format suffix pattern will be used. Example: @@ -33,7 +33,7 @@ Example: url(r'^comments/$', views.comment_list), url(r'^comments/(?P[0-9]+)/$', views.comment_detail) ] - + urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'html']) When using `format_suffix_patterns`, you must make sure to add the `'format'` keyword argument to the corresponding views. For example: @@ -56,12 +56,12 @@ The name of the kwarg used may be modified by using the `FORMAT_SUFFIX_KWARG` se Also note that `format_suffix_patterns` does not support descending into `include` URL patterns. --- - + ## Accept headers vs. format suffixes There seems to be a view among some of the Web community that filename extensions are not a RESTful pattern, and that `HTTP Accept` headers should always be used instead. -It is actually a misconception. For example, take the following quote from Roy Fielding discussing the relative merits of query parameter media-type indicators vs. file extension media-type indicators: +It is actually a misconception. For example, take the following quote from Roy Fielding discussing the relative merits of query parameter media-type indicators vs. file extension media-type indicators: “That's why I always prefer extensions. Neither choice has anything to do with REST.” — Roy Fielding, [REST discuss mailing list][cite2] diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 49a5e58f0..648ece827 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -1,5 +1,5 @@ - - +source: mixins.py + generics.py # Generic views diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index e57aed1a9..9b7086c54 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -1,4 +1,4 @@ - +source: pagination.py # Pagination @@ -6,7 +6,7 @@ > > — [Django documentation][cite] -REST framework includes a `PaginationSerializer` class that makes it easy to return paginated data in a way that can then be rendered to arbitrary media types. +REST framework includes a `PaginationSerializer` class that makes it easy to return paginated data in a way that can then be rendered to arbitrary media types. ## Paginating basic data @@ -33,7 +33,7 @@ The `context` argument of the `PaginationSerializer` class may optionally includ request = RequestFactory().get('/foobar') serializer = PaginationSerializer(instance=page, context={'request': request}) serializer.data - # {'count': 4, 'next': 'http://testserver/foobar?page=2', 'previous': None, 'results': [u'john', u'paul']} + # {'count': 4, 'next': 'http://testserver/foobar?page=2', 'previous': None, 'results': [u'john', u'paul']} We could now return that data in a `Response` object, and it would be rendered into the correct media type. diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md index 72a4af643..42d77b223 100644 --- a/docs/api-guide/parsers.md +++ b/docs/api-guide/parsers.md @@ -1,4 +1,4 @@ - +source: parsers.py # Parsers @@ -161,7 +161,7 @@ By default this will include the following keys: `view`, `request`, `args`, `kwa ## Example -The following is an example plaintext parser that will populate the `request.DATA` property with a string representing the body of the request. +The following is an example plaintext parser that will populate the `request.DATA` property with a string representing the body of the request. class PlainTextParser(BaseParser): """ @@ -197,4 +197,4 @@ The following third party packages are also available. [juanriaza]: https://github.com/juanriaza [vbabiy]: https://github.com/vbabiy [djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack -[djangorestframework-camel-case]: https://github.com/vbabiy/djangorestframework-camel-case \ No newline at end of file +[djangorestframework-camel-case]: https://github.com/vbabiy/djangorestframework-camel-case diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index 446e362e1..f068f0f72 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -1,4 +1,4 @@ - +source: permissions.py # Permissions @@ -12,7 +12,7 @@ Permission checks are always run at the very start of the view, before any other ## How permissions are determined -Permissions in REST framework are always defined as a list of permission classes. +Permissions in REST framework are always defined as a list of permission classes. Before running the main body of the view each permission in the list is checked. If any permission check fails an `exceptions.PermissionDenied` exception will be raised, and the main body of the view will not run. @@ -220,9 +220,9 @@ As well as global permissions, that are run against all incoming requests, you c def has_object_permission(self, request, view, obj): # Read permissions are allowed to any request, # so we'll always allow GET, HEAD or OPTIONS requests. - if request.method in permissions.SAFE_METHODS: + if request.method in permissions.SAFE_METHODS: return True - + # Instance must have an attribute named `owner`. return obj.owner == request.user diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md index d03a75ae5..ad981b2bb 100644 --- a/docs/api-guide/relations.md +++ b/docs/api-guide/relations.md @@ -1,4 +1,4 @@ - +source: relations.py # Serializer relations @@ -33,7 +33,7 @@ In order to explain the various types of relational fields, we'll use a couple o class Meta: unique_together = ('album', 'order') order_by = 'order' - + def __unicode__(self): return '%d: %s' % (self.order, self.title) @@ -42,10 +42,10 @@ In order to explain the various types of relational fields, we'll use a couple o `RelatedField` may be used to represent the target of the relationship using its `__unicode__` method. For example, the following serializer. - + class AlbumSerializer(serializers.ModelSerializer): tracks = serializers.RelatedField(many=True) - + class Meta: model = Album fields = ('album_name', 'artist', 'tracks') @@ -74,10 +74,10 @@ This field is read only. `PrimaryKeyRelatedField` may be used to represent the target of the relationship using its primary key. For example, the following serializer: - + class AlbumSerializer(serializers.ModelSerializer): tracks = serializers.PrimaryKeyRelatedField(many=True, read_only=True) - + class Meta: model = Album fields = ('album_name', 'artist', 'tracks') @@ -108,11 +108,11 @@ By default this field is read-write, although you can change this behavior using `HyperlinkedRelatedField` may be used to represent the target of the relationship using a hyperlink. For example, the following serializer: - + class AlbumSerializer(serializers.ModelSerializer): tracks = serializers.HyperlinkedRelatedField(many=True, read_only=True, view_name='track-detail') - + class Meta: model = Album fields = ('album_name', 'artist', 'tracks') @@ -146,11 +146,11 @@ By default this field is read-write, although you can change this behavior using `SlugRelatedField` may be used to represent the target of the relationship using a field on the target. For example, the following serializer: - + class AlbumSerializer(serializers.ModelSerializer): tracks = serializers.SlugRelatedField(many=True, read_only=True, slug_field='title') - + class Meta: model = Album fields = ('album_name', 'artist', 'tracks') @@ -222,10 +222,10 @@ For example, the following serializer: class Meta: model = Track fields = ('order', 'title') - + class AlbumSerializer(serializers.ModelSerializer): tracks = TrackSerializer(many=True) - + class Meta: model = Album fields = ('album_name', 'artist', 'tracks') @@ -262,7 +262,7 @@ For, example, we could define a relational field, to serialize a track to a cust class AlbumSerializer(serializers.ModelSerializer): tracks = TrackListingField(many=True) - + class Meta: model = Album fields = ('album_name', 'artist', 'tracks') @@ -302,7 +302,7 @@ If you have not set a related name for the reverse relationship, you'll need to class AlbumSerializer(serializers.ModelSerializer): class Meta: - fields = ('track_set', ...) + fields = ('track_set', ...) See the Django documentation on [reverse relationships][reverse-relationships] for more details. @@ -315,14 +315,14 @@ For example, given the following model for a tag, which has a generic relationsh class TaggedItem(models.Model): """ Tags arbitrary model instances using a generic relation. - + See: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/ """ tag_name = models.SlugField() content_type = models.ForeignKey(ContentType) object_id = models.PositiveIntegerField() tagged_object = GenericForeignKey('content_type', 'object_id') - + def __unicode__(self): return self.tag @@ -353,7 +353,7 @@ We could define a custom field that could be used to serialize tagged instances, def to_native(self, value): """ Serialize tagged objects to a simple textual representation. - """ + """ if isinstance(value, Bookmark): return 'Bookmark: ' + value.url elif isinstance(value, Note): @@ -366,7 +366,7 @@ If you need the target of the relationship to have a nested representation, you """ Serialize bookmark instances using a bookmark serializer, and note instances using a note serializer. - """ + """ if isinstance(value, Bookmark): serializer = BookmarkSerializer(value) elif isinstance(value, Note): @@ -391,7 +391,7 @@ to ``True``. ## Advanced Hyperlinked fields -If you have very specific requirements for the style of your hyperlinked relationships you can override `HyperlinkedRelatedField`. +If you have very specific requirements for the style of your hyperlinked relationships you can override `HyperlinkedRelatedField`. There are two methods you'll need to override. @@ -411,7 +411,7 @@ May raise an `ObjectDoesNotExist` exception. ### Example -For example, if all your object URLs used both a account and a slug in the the URL to reference the object, you might create a custom field like this: +For example, if all your object URLs used both a account and a slug in the the URL to reference the object, you might create a custom field like this: class CustomHyperlinkedField(serializers.HyperlinkedRelatedField): def get_url(self, obj, view_name, request, format): diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index db7436c23..035ec1d27 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -1,4 +1,4 @@ - +source: renderers.py # Renderers @@ -115,7 +115,7 @@ The `jsonp` approach is essentially a browser hack, and is [only appropriate for ## YAMLRenderer -Renders the request data into `YAML`. +Renders the request data into `YAML`. Requires the `pyyaml` package to be installed. @@ -131,7 +131,7 @@ Note that non-ascii characters will be rendered using `\uXXXX` character escape. ## UnicodeYAMLRenderer -Renders the request data into `YAML`. +Renders the request data into `YAML`. Requires the `pyyaml` package to be installed. @@ -184,7 +184,7 @@ An example of a view that uses `TemplateHTMLRenderer`: def get(self, request, *args, **kwargs): self.object = self.get_object() return Response({'user': self.object}, template_name='user_detail.html') - + You can use `TemplateHTMLRenderer` either to return regular HTML pages using REST framework, or to return both HTML and API responses from a single endpoint. If you're building websites that use `TemplateHTMLRenderer` along with other renderer classes, you should consider listing `TemplateHTMLRenderer` as the first class in the `renderer_classes` list, so that it will be prioritised first even for browsers that send poorly formed `ACCEPT:` headers. @@ -205,7 +205,7 @@ An example of a view that uses `TemplateHTMLRenderer`: @api_view(('GET',)) @renderer_classes((StaticHTMLRenderer,)) - def simple_html_view(request): + def simple_html_view(request): data = '

    Hello, world

    ' return Response(data) @@ -300,7 +300,7 @@ The following is an example plaintext renderer that will return a response with class PlainTextRenderer(renderers.BaseRenderer): media_type = 'text/plain' format = 'txt' - + def render(self, data, media_type=None, renderer_context=None): return data.encode(self.charset) @@ -340,7 +340,7 @@ You can do some pretty flexible things using REST framework's renderers. Some e * Provide either flat or nested representations from the same endpoint, depending on the requested media type. * Serve both regular HTML webpages, and JSON based API responses from the same endpoints. * Specify multiple types of HTML representation for API clients to use. -* Underspecify a renderer's media type, such as using `media_type = 'image/*'`, and use the `Accept` header to vary the encoding of the response. +* Underspecify a renderer's media type, such as using `media_type = 'image/*'`, and use the `Accept` header to vary the encoding of the response. ## Varying behaviour by media type diff --git a/docs/api-guide/requests.md b/docs/api-guide/requests.md index 87425ed1b..8713fa2a6 100644 --- a/docs/api-guide/requests.md +++ b/docs/api-guide/requests.md @@ -1,4 +1,4 @@ - +source: request.py # Requests @@ -105,7 +105,7 @@ REST framework supports a few browser enhancements such as browser-based `PUT`, Browser-based `PUT`, `PATCH` and `DELETE` forms are transparently supported. -For more information see the [browser enhancements documentation]. +For more information see the [browser enhancements documentation]. ## .content_type @@ -115,7 +115,7 @@ You won't typically need to directly access the request's content type, as you'l If you do need to access the content type of the request you should use the `.content_type` property in preference to using `request.META.get('HTTP_CONTENT_TYPE')`, as it provides transparent support for browser-based non-form content. -For more information see the [browser enhancements documentation]. +For more information see the [browser enhancements documentation]. ## .stream @@ -125,7 +125,7 @@ You won't typically need to directly access the request's content, as you'll nor If you do need to access the raw content directly, you should use the `.stream` property in preference to using `request.content`, as it provides transparent support for browser-based non-form content. -For more information see the [browser enhancements documentation]. +For more information see the [browser enhancements documentation]. --- diff --git a/docs/api-guide/responses.md b/docs/api-guide/responses.md index 5a42aa923..97f312710 100644 --- a/docs/api-guide/responses.md +++ b/docs/api-guide/responses.md @@ -1,4 +1,4 @@ - +source: response.py # Responses @@ -90,6 +90,6 @@ The `Response` class extends `SimpleTemplateResponse`, and all the usual attribu As with any other `TemplateResponse`, this method is called to render the serialized data of the response into the final response content. When `.render()` is called, the response content will be set to the result of calling the `.render(data, accepted_media_type, renderer_context)` method on the `accepted_renderer` instance. You won't typically need to call `.render()` yourself, as it's handled by Django's standard response cycle. - + [cite]: https://docs.djangoproject.com/en/dev/ref/template-response/ [statuscodes]: status-codes.md diff --git a/docs/api-guide/reverse.md b/docs/api-guide/reverse.md index 383eca4ce..71fb83f9e 100644 --- a/docs/api-guide/reverse.md +++ b/docs/api-guide/reverse.md @@ -1,4 +1,4 @@ - +source: reverse.py # Returning URLs @@ -30,7 +30,7 @@ You should **include the request as a keyword argument** to the function, for ex from rest_framework.reverse import reverse from rest_framework.views import APIView from django.utils.timezone import now - + class APIRootView(APIView): def get(self, request): year = now().year diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md index 61a476b8b..080230faf 100644 --- a/docs/api-guide/routers.md +++ b/docs/api-guide/routers.md @@ -1,4 +1,4 @@ - +source: routers.py # Routers @@ -56,10 +56,10 @@ For example, given a method like this on the `UserViewSet` class: from myapp.permissions import IsAdminOrIsSelf from rest_framework.decorators import detail_route - + class UserViewSet(ModelViewSet): ... - + @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf]) def set_password(self, request, pk=None): ... @@ -228,7 +228,7 @@ For another example of setting the `.routes` attribute, see the source code for ## Advanced custom routers -If you want to provide totally custom behavior, you can override `BaseRouter` and override the `get_urls(self)` method. The method should inspect the registered viewsets and return a list of URL patterns. The registered prefix, viewset and basename tuples may be inspected by accessing the `self.registry` attribute. +If you want to provide totally custom behavior, you can override `BaseRouter` and override the `get_urls(self)` method. The method should inspect the registered viewsets and return a list of URL patterns. The registered prefix, viewset and basename tuples may be inspected by accessing the `self.registry` attribute. You may also want to override the `get_default_base_name(self, viewset)` method, or else always explicitly set the `base_name` argument when registering your viewsets with the router. diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index eeeffa136..2d0ff79a4 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -1,4 +1,4 @@ - +source: serializers.py # Serializers @@ -21,7 +21,7 @@ Let's start by creating a simple object we can use for example purposes: self.email = email self.content = content self.created = created or datetime.datetime.now() - + comment = Comment(email='leila@example.com', content='foo bar') We'll declare a serializer that we can use to serialize and deserialize `Comment` objects. @@ -45,7 +45,7 @@ Declaring a serializer looks very similar to declaring a form: instance.content = attrs.get('content', instance.content) instance.created = attrs.get('created', instance.created) return instance - return Comment(**attrs) + return Comment(**attrs) The first part of serializer class defines the fields that get serialized/deserialized. The `restore_object` method defines how fully fledged instances get created when deserializing data. @@ -83,8 +83,8 @@ If you need to customize the serialized value of a particular field, you can do These methods are essentially the reverse of `validate_` (see *Validation* below.) ## Deserializing objects - -Deserialization is similar. First we parse a stream into Python native datatypes... + +Deserialization is similar. First we parse a stream into Python native datatypes... from StringIO import StringIO from rest_framework.parsers import JSONParser @@ -174,7 +174,7 @@ To save the deserialized objects created by a serializer, call the `.save()` met The default behavior of the method is to simply call `.save()` on the deserialized object instance. You can override the default save behaviour by overriding the `.save_object(obj)` method on the serializer class. -The generic views provided by REST framework call the `.save()` method when updating or creating entities. +The generic views provided by REST framework call the `.save()` method when updating or creating entities. ## Dealing with nested objects @@ -288,12 +288,12 @@ By default the serializer class will use the `id` key on the incoming data to de slug = serializers.CharField(max_length=100) created = serializers.DateTimeField() ... # Various other fields - + def get_identity(self, data): """ This hook is required for bulk update. We need to override the default, to use the slug as the identity. - + Note that the data has not yet been validated at this point, so we need to deal gracefully with incorrect datatypes. """ @@ -361,7 +361,7 @@ The `depth` option should be set to an integer value that indicates the depth of If you want to customize the way the serialization is done (e.g. using `allow_add_remove`) you'll need to define the field yourself. -## Specifying which fields should be read-only +## Specifying which fields should be read-only You may wish to specify multiple fields as read-only. Instead of adding each field explicitly with the `read_only=True` attribute, you may use the `read_only_fields` Meta option, like so: @@ -371,9 +371,9 @@ You may wish to specify multiple fields as read-only. Instead of adding each fi fields = ('id', 'account_name', 'users', 'created') read_only_fields = ('account_name',) -Model fields which have `editable=False` set, and `AutoField` fields will be set to read-only by default, and do not need to be added to the `read_only_fields` option. +Model fields which have `editable=False` set, and `AutoField` fields will be set to read-only by default, and do not need to be added to the `read_only_fields` option. -## Specifying which fields should be write-only +## Specifying which fields should be write-only You may wish to specify multiple fields as write-only. Instead of adding each field explicitly with the `write_only=True` attribute, you may use the `write_only_fields` Meta option, like so: @@ -387,12 +387,12 @@ You may wish to specify multiple fields as write-only. Instead of adding each f """ Instantiate a new User instance. """ - assert instance is None, 'Cannot update users with CreateUserSerializer' + assert instance is None, 'Cannot update users with CreateUserSerializer' user = User(email=attrs['email'], username=attrs['username']) user.set_password(attrs['password']) return user - -## Specifying fields explicitly + +## Specifying fields explicitly You can add extra fields to a `ModelSerializer` or override the default fields by declaring fields on the class, just as you would for a `Serializer` class. @@ -524,10 +524,10 @@ For example, if you wanted to be able to set which fields should be used by a se def __init__(self, *args, **kwargs): # Don't pass the 'fields' arg up to the superclass fields = kwargs.pop('fields', None) - + # Instantiate the superclass normally super(DynamicFieldsModelSerializer, self).__init__(*args, **kwargs) - + if fields: # Drop any fields that are not specified in the `fields` argument. allowed = set(fields) @@ -550,7 +550,7 @@ This would then allow you to do the following: ## Customising the default fields -The `field_mapping` attribute is a dictionary that maps model classes to serializer classes. Overriding the attribute will let you set a different set of default serializer classes. +The `field_mapping` attribute is a dictionary that maps model classes to serializer classes. Overriding the attribute will let you set a different set of default serializer classes. For more advanced customization than simply changing the default serializer class you can override various `get__field` methods. Doing so will allow you to customize the arguments that each serializer field is initialized with. Each of these methods may either return a field or serializer instance, or `None`. diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 96d715ea2..0aa4b6a97 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -1,4 +1,4 @@ - +source: settings.py # Settings diff --git a/docs/api-guide/status-codes.md b/docs/api-guide/status-codes.md index 64c464349..d81e092c5 100644 --- a/docs/api-guide/status-codes.md +++ b/docs/api-guide/status-codes.md @@ -1,4 +1,4 @@ - +source: status.py # Status Codes @@ -27,7 +27,7 @@ The module also includes a set of helper functions for testing if a status code url = reverse('index') response = self.client.get(url) self.assertTrue(status.is_success(response.status_code)) - + For more information on proper usage of HTTP status codes see [RFC 2616][rfc2616] and [RFC 6585][rfc6585]. @@ -51,7 +51,7 @@ This class of status code indicates that the client's request was successfully r HTTP_205_RESET_CONTENT HTTP_206_PARTIAL_CONTENT -## Redirection - 3xx +## Redirection - 3xx This class of status code indicates that further action needs to be taken by the user agent in order to fulfill the request. diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md index 72c339613..d059fdab5 100644 --- a/docs/api-guide/testing.md +++ b/docs/api-guide/testing.md @@ -1,4 +1,4 @@ - +source: test.py # Testing @@ -170,7 +170,7 @@ This can be a useful shortcut if you're testing the API but don't want to have t To unauthenticate subsequent requests, call `force_authenticate` setting the user and/or token to `None`. - client.force_authenticate(user=None) + client.force_authenticate(user=None) ## CSRF validation @@ -197,7 +197,7 @@ You can use any of REST framework's test case classes as you would for the regul from django.core.urlresolvers import reverse from rest_framework import status - from rest_framework.test import APITestCase + from rest_framework.test import APITestCase class AccountTests(APITestCase): def test_create_account(self): diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index 147c16ff7..3f668867c 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -1,4 +1,4 @@ - +source: throttling.py # Throttling @@ -83,7 +83,7 @@ The throttle classes provided by REST framework use Django's cache backend. You If you need to use a cache other than `'default'`, you can do so by creating a custom throttle class and setting the `cache` attribute. For example: class CustomAnonRateThrottle(AnonRateThrottle): - cache = get_cache('alternate') + cache = get_cache('alternate') You'll need to remember to also set your custom throttle class in the `'DEFAULT_THROTTLE_CLASSES'` settings key, or using the `throttle_classes` view attribute. @@ -147,15 +147,15 @@ For example, given the following views... class ContactListView(APIView): throttle_scope = 'contacts' ... - + class ContactDetailView(ApiView): throttle_scope = 'contacts' ... - class UploadView(APIView): + class UploadView(APIView): throttle_scope = 'uploads' ... - + ...and the following settings. REST_FRAMEWORK = { diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md index 194a7a6b3..31c62682f 100644 --- a/docs/api-guide/views.md +++ b/docs/api-guide/views.md @@ -1,4 +1,5 @@ - +source: decorators.py + views.py # Class Based Views @@ -26,7 +27,7 @@ For example: class ListUsers(APIView): """ View to list all users in the system. - + * Requires token authentication. * Only admin users are able to access this view. """ @@ -54,7 +55,7 @@ The following attributes control the pluggable aspects of API views. ### .permission_classes -### .content_negotiation_class +### .content_negotiation_class ## API policy instantiation methods diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index 9030e3ee0..9249d8756 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -1,4 +1,4 @@ - +source: viewsets.py # ViewSets diff --git a/docs/theme/content.html b/docs/theme/content.html new file mode 100644 index 000000000..93a437ff8 --- /dev/null +++ b/docs/theme/content.html @@ -0,0 +1,11 @@ +{% if meta.source %} + + {% for filename in meta.source %} + + {{ filename }} + + {% endfor %} + +{% endif %} + +{{ content }} diff --git a/docs_theme/base.html b/docs_theme/base.html index 4ca6cd810..07582392f 100644 --- a/docs_theme/base.html +++ b/docs_theme/base.html @@ -118,7 +118,7 @@ a.fusion-poweredby {
    - {{ content }} + {% include "content.html" %}
    From 361827350a8bd4efb4d6a09bcb29c0185a5454ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Padilla?= Date: Fri, 31 Oct 2014 10:25:19 -0400 Subject: [PATCH 23/47] Move content template into base.html --- docs/theme/content.html | 11 ----------- docs_theme/base.html | 10 +++++++++- 2 files changed, 9 insertions(+), 12 deletions(-) delete mode 100644 docs/theme/content.html diff --git a/docs/theme/content.html b/docs/theme/content.html deleted file mode 100644 index 93a437ff8..000000000 --- a/docs/theme/content.html +++ /dev/null @@ -1,11 +0,0 @@ -{% if meta.source %} - - {% for filename in meta.source %} - - {{ filename }} - - {% endfor %} - -{% endif %} - -{{ content }} diff --git a/docs_theme/base.html b/docs_theme/base.html index 07582392f..67290df60 100644 --- a/docs_theme/base.html +++ b/docs_theme/base.html @@ -118,7 +118,15 @@ a.fusion-poweredby {
    - {% include "content.html" %} + {% if meta.source %} + {% for filename in meta.source %} + + {{ filename }} + + {% endfor %} + {% endif %} + + {{ content }}
    From 3bfc82068b068defee470910a850757e4c12df3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Padilla?= Date: Fri, 31 Oct 2014 11:38:27 -0400 Subject: [PATCH 24/47] Update tabbing and cleanup theme templates --- docs_theme/404.html | 197 +++++++++++++++++++---------------- docs_theme/base.html | 241 +++++++++++++++++++++++-------------------- docs_theme/nav.html | 51 +++++---- 3 files changed, 258 insertions(+), 231 deletions(-) diff --git a/docs_theme/404.html b/docs_theme/404.html index 864247e78..44993e37d 100644 --- a/docs_theme/404.html +++ b/docs_theme/404.html @@ -1,50 +1,54 @@ - - - Django REST framework - 404 - Page not found - - - - - - - - - - + + + + Django REST framework - 404 - Page not found + + + + + - - + + + + + - + - - - +
    - GitHub - Next - Previous - Search + GitHub + Next + Previous + Search @@ -121,81 +125,92 @@ --> -
    +
    +
    - - - + +

    404

    -

    Page not found

    +

    Page not found +

    Try the homepage, or search the documentation.

    -
    -
    -
    -
    + + + + + + + + -
    - +
    + + - - - - - - + + + + - // Dynamically force sidenav to no higher than browser window - $('.side-nav').css('max-height', window.innerHeight - 130); - - $(function(){ - $(window).resize(function(){ - $('.side-nav').css('max-height', window.innerHeight - 130); - }); - }); - - + diff --git a/docs_theme/base.html b/docs_theme/base.html index 67290df60..544e21881 100644 --- a/docs_theme/base.html +++ b/docs_theme/base.html @@ -1,56 +1,62 @@ - - - {{ page_title }} - - - - - - - - - - + + + + {{ page_title }} + + + + + - - + + + + + - - - + +{# TODO: This is a bit of a hack. We don't want to refer to the file specifically. #} -a.fusion-poweredby { - display: block; - margin-top: 10px; -} -@media (max-width: 767px) { - div.promo {display: none;} -} - - - {# TODO: This is a bit of a hack. We don't want to refer to the file specifically. #} - +
    @@ -59,32 +65,34 @@ a.fusion-poweredby {
    - - + +
    @@ -98,18 +106,16 @@ a.fusion-poweredby {
      {% for toc_item in toc %} -
    • {{ toc_item.title }}
      • - {% for toc_item in toc_item.children %} -
    • {{ toc_item.title }}
      • - {% endfor %} - {% endfor %} - - {# TODO: This is a bit of a hack. We don't want to refer to the file specifically. #} - {% if current_page.input_path == 'index.md' %} -
      -
      - -
      +
    • {{ toc_item.title }} +
      • + {% for toc_item in toc_item.children %} +
    • {{ toc_item.title }} +
      • + {% endfor %} {% endfor %} {# TODO: This is a bit of a hack. We don't want to refer to the file specifically. #} {% if current_page.input_path == 'index.md' %} +
      +
      + +
      {% endif %}
    @@ -127,42 +133,51 @@ a.fusion-poweredby { {% endif %} {{ content }} -
    -
    -
    -
    - -
    -
    + + + + + + + + +
    + + - - - - - + + + + + - + - // Dynamically force sidenav to no higher than browser window - $('.side-nav').css('max-height', window.innerHeight - 130); - - $(function(){ - $(window).resize(function(){ - $('.side-nav').css('max-height', window.innerHeight - 130); - }); - }); - - + diff --git a/docs_theme/nav.html b/docs_theme/nav.html index a7a72d68e..87e197b35 100644 --- a/docs_theme/nav.html +++ b/docs_theme/nav.html @@ -1,11 +1,10 @@ -
    - GitHub - Next - Previous - Search + GitHub + Next + Previous + Search @@ -14,31 +13,29 @@ Django REST framework
    {% if include_nav %} - - {% endif %} -
    +
    +
    From 06683b86b2b15153df52fe481b5c4eeb489a80cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Padilla?= Date: Fri, 31 Oct 2014 13:02:11 -0400 Subject: [PATCH 25/47] Use single quotes for consistency Conflicts: mkdocs.yml --- mkdocs.yml | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 2d1886a05..c70de9822 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,30 +13,30 @@ pages: - ['tutorial/4-authentication-and-permissions.md', ] - ['tutorial/5-relationships-and-hyperlinked-apis.md', ] - ['tutorial/6-viewsets-and-routers.md', ] - - ['api-guide/requests.md', "API Guide", ] - - ['api-guide/responses.md', "API Guide", ] - - ['api-guide/views.md', "API Guide", ] - - ['api-guide/generic-views.md', "API Guide", ] - - ['api-guide/viewsets.md', "API Guide", ] - - ['api-guide/routers.md', "API Guide", ] - - ['api-guide/parsers.md', "API Guide", ] - - ['api-guide/renderers.md', "API Guide", ] - - ['api-guide/serializers.md', "API Guide", ] - - ['api-guide/fields.md', "API Guide", ] - - ['api-guide/relations.md', "API Guide", ] - - ['api-guide/validators.md', "API Guide", ] - - ['api-guide/authentication.md', "API Guide", ] - - ['api-guide/permissions.md', "API Guide", ] - - ['api-guide/throttling.md', "API Guide", ] - - ['api-guide/filtering.md', "API Guide", ] - - ['api-guide/pagination.md', "API Guide", ] - - ['api-guide/content-negotiation.md', "API Guide", ] - - ['api-guide/format-suffixes.md', "API Guide", ] - - ['api-guide/reverse.md', "API Guide", ] - - ['api-guide/exceptions.md', "API Guide", ] - - ['api-guide/status-codes.md', "API Guide", ] - - ['api-guide/testing.md', "API Guide", ] - - ['api-guide/settings.md', "API Guide", ] + - ['api-guide/requests.md', 'API Guide', ] + - ['api-guide/responses.md', 'API Guide', ] + - ['api-guide/views.md', 'API Guide', ] + - ['api-guide/generic-views.md', 'API Guide', ] + - ['api-guide/viewsets.md', 'API Guide', ] + - ['api-guide/routers.md', 'API Guide', ] + - ['api-guide/parsers.md', 'API Guide', ] + - ['api-guide/renderers.md', 'API Guide', ] + - ['api-guide/serializers.md', 'API Guide', ] + - ['api-guide/fields.md', 'API Guide', ] + - ['api-guide/relations.md', 'API Guide', ] + - ['api-guide/validators.md', 'API Guide', ] + - ['api-guide/authentication.md', 'API Guide', ] + - ['api-guide/permissions.md', 'API Guide', ] + - ['api-guide/throttling.md', 'API Guide', ] + - ['api-guide/filtering.md', 'API Guide', ] + - ['api-guide/pagination.md', 'API Guide', ] + - ['api-guide/content-negotiation.md', 'API Guide', ] + - ['api-guide/format-suffixes.md', 'API Guide', ] + - ['api-guide/reverse.md', 'API Guide', ] + - ['api-guide/exceptions.md', 'API Guide', ] + - ['api-guide/status-codes.md', 'API Guide', ] + - ['api-guide/testing.md', 'API Guide', ] + - ['api-guide/settings.md', 'API Guide', ] - ['topics/documenting-your-api.md', ] - ['topics/ajax-csrf-cors.md', ] - ['topics/browser-enhancements.md', ] From 200e0b17daecd07de6d1f9926a430d29b3ee948f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Padilla?= Date: Fri, 31 Oct 2014 13:03:39 -0400 Subject: [PATCH 26/47] Clean up extra white space --- docs/topics/2.2-announcement.md | 8 ++++---- docs/topics/2.3-announcement.md | 8 ++++---- docs/topics/documenting-your-api.md | 8 ++++---- docs/topics/kickstarter-announcement.md | 2 +- docs/topics/release-notes.md | 2 +- docs/topics/rest-framework-2-announcement.md | 4 ++-- docs/topics/writable-nested-serializers.md | 10 +++++----- docs/tutorial/1-serialization.md | 2 +- 8 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/topics/2.2-announcement.md b/docs/topics/2.2-announcement.md index a997c7829..1df52cff2 100644 --- a/docs/topics/2.2-announcement.md +++ b/docs/topics/2.2-announcement.md @@ -42,7 +42,7 @@ The 2.2 release makes a few changes to the API, in order to make it more consist The `ManyRelatedField()` style is being deprecated in favor of a new `RelatedField(many=True)` syntax. -For example, if a user is associated with multiple questions, which we want to represent using a primary key relationship, we might use something like the following: +For example, if a user is associated with multiple questions, which we want to represent using a primary key relationship, we might use something like the following: class UserSerializer(serializers.HyperlinkedModelSerializer): questions = serializers.PrimaryKeyRelatedField(many=True) @@ -58,10 +58,10 @@ The change also applies to serializers. If you have a nested serializer, you sh class Meta: model = Track fields = ('name', 'duration') - + class AlbumSerializer(serializer.ModelSerializer): tracks = TrackSerializer(many=True) - + class Meta: model = Album fields = ('album_name', 'artist', 'tracks') @@ -87,7 +87,7 @@ For example, is a user account has an optional foreign key to a company, that yo This is in line both with the rest of the serializer fields API, and with Django's `Form` and `ModelForm` API. -Using `required` throughout the serializers API means you won't need to consider if a particular field should take `blank` or `null` arguments instead of `required`, and also means there will be more consistent behavior for how fields are treated when they are not present in the incoming data. +Using `required` throughout the serializers API means you won't need to consider if a particular field should take `blank` or `null` arguments instead of `required`, and also means there will be more consistent behavior for how fields are treated when they are not present in the incoming data. The `null=True` argument will continue to function, and will imply `required=False`, but will raise a `PendingDeprecationWarning`. diff --git a/docs/topics/2.3-announcement.md b/docs/topics/2.3-announcement.md index 7c800afa0..9c9f3e9f6 100644 --- a/docs/topics/2.3-announcement.md +++ b/docs/topics/2.3-announcement.md @@ -27,7 +27,7 @@ As an example of just how simple REST framework APIs can now be, here's an API w class GroupViewSet(viewsets.ModelViewSet): model = Group - + # Routers provide an easy way of automatically determining the URL conf router = routers.DefaultRouter() router.register(r'users', UserViewSet) @@ -197,13 +197,13 @@ Usage of the old-style attributes continues to be supported, but will raise a `P For most cases APIs using model fields will behave as previously, however if you are using a custom renderer, not provided by REST framework, then you may now need to add support for rendering `Decimal` instances to your renderer implementation. -## ModelSerializers and reverse relationships +## ModelSerializers and reverse relationships The support for adding reverse relationships to the `fields` option on a `ModelSerializer` class means that the `get_related_field` and `get_nested_field` method signatures have now changed. In the unlikely event that you're providing a custom serializer class, and implementing these methods you should note the new call signature for both methods is now `(self, model_field, related_model, to_many)`. For reverse relationships `model_field` will be `None`. -The old-style signature will continue to function but will raise a `PendingDeprecationWarning`. +The old-style signature will continue to function but will raise a `PendingDeprecationWarning`. ## View names and descriptions @@ -211,7 +211,7 @@ The mechanics of how the names and descriptions used in the browseable API are g If you've been customizing this behavior, for example perhaps to use `rst` markup for the browseable API, then you'll need to take a look at the implementation to see what updates you need to make. -Note that the relevant methods have always been private APIs, and the docstrings called them out as intended to be deprecated. +Note that the relevant methods have always been private APIs, and the docstrings called them out as intended to be deprecated. --- diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index e20f97122..d65e251f1 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -54,7 +54,7 @@ The title that is used in the browsable API is generated from the view class nam For example, the view `UserListView`, will be named `User List` when presented in the browsable API. -When working with viewsets, an appropriate suffix is appended to each generated view. For example, the view set `UserViewSet` will generate views named `User List` and `User Instance`. +When working with viewsets, an appropriate suffix is appended to each generated view. For example, the view set `UserViewSet` will generate views named `User List` and `User Instance`. #### Setting the description @@ -65,9 +65,9 @@ If the python `markdown` library is installed, then [markdown syntax][markdown] class AccountListView(views.APIView): """ Returns a list of all **active** accounts in the system. - + For more details on how accounts are activated please [see here][ref]. - + [ref]: http://example.com/activating-accounts """ @@ -84,7 +84,7 @@ You can modify the response behavior to `OPTIONS` requests by overriding the `me def metadata(self, request): """ Don't include the view description in OPTIONS responses. - """ + """ data = super(ExampleView, self).metadata(request) data.pop('description') return data diff --git a/docs/topics/kickstarter-announcement.md b/docs/topics/kickstarter-announcement.md index 7d1f6d0eb..e8bad95be 100644 --- a/docs/topics/kickstarter-announcement.md +++ b/docs/topics/kickstarter-announcement.md @@ -160,4 +160,4 @@ The following individuals made a significant financial contribution to the devel ### Supporters -There were also almost 300 further individuals choosing to help fund the project at other levels or choosing to give anonymously. Again, thank you, thank you, thank you! \ No newline at end of file +There were also almost 300 further individuals choosing to help fund the project at other levels or choosing to give anonymously. Again, thank you, thank you, thank you! diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 88780c3fb..9fca949ab 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -63,7 +63,7 @@ You can determine your currently installed version using `pip freeze`: * Bugfix: Fix migration in `authtoken` application. * Bugfix: Allow selection of integer keys in nested choices. * Bugfix: Return `None` instead of `'None'` in `CharField` with `allow_none=True`. -* Bugfix: Ensure custom model fields map to equivelent serializer fields more reliably. +* Bugfix: Ensure custom model fields map to equivelent serializer fields more reliably. * Bugfix: `DjangoFilterBackend` no longer quietly changes queryset ordering. ### 2.4.2 diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md index f1060d90b..a7746932e 100644 --- a/docs/topics/rest-framework-2-announcement.md +++ b/docs/topics/rest-framework-2-announcement.md @@ -8,7 +8,7 @@ What it is, and why you should care. --- -**Announcement:** REST framework 2 released - Tue 30th Oct 2012 +**Announcement:** REST framework 2 released - Tue 30th Oct 2012 --- @@ -37,7 +37,7 @@ REST framework 2 includes a totally re-worked serialization engine, that was ini * A declarative serialization API, that mirrors Django's `Forms`/`ModelForms` API. * Structural concerns are decoupled from encoding concerns. * Able to support rendering and parsing to many formats, including both machine-readable representations and HTML forms. -* Validation that can be mapped to obvious and comprehensive error responses. +* Validation that can be mapped to obvious and comprehensive error responses. * Serializers that support both nested, flat, and partially-nested representations. * Relationships that can be expressed as primary keys, hyperlinks, slug fields, and other custom representations. diff --git a/docs/topics/writable-nested-serializers.md b/docs/topics/writable-nested-serializers.md index abc6a82f7..ed614bd24 100644 --- a/docs/topics/writable-nested-serializers.md +++ b/docs/topics/writable-nested-serializers.md @@ -8,7 +8,7 @@ Although flat data structures serve to properly delineate between the individual Nested data structures are easy enough to work with if they're read-only - simply nest your serializer classes and you're good to go. However, there are a few more subtleties to using writable nested serializers, due to the dependencies between the various model instances, and the need to save or delete multiple instances in a single action. -## One-to-many data structures +## One-to-many data structures *Example of a **read-only** nested serializer. Nothing complex to worry about here.* @@ -16,10 +16,10 @@ Nested data structures are easy enough to work with if they're read-only - simpl class Meta: model = ToDoItem fields = ('text', 'is_completed') - + class ToDoListSerializer(serializers.ModelSerializer): items = ToDoItemSerializer(many=True, read_only=True) - + class Meta: model = ToDoList fields = ('title', 'items') @@ -31,7 +31,7 @@ Some example output from our serializer. 'items': { {'text': 'Compile playlist', 'is_completed': True}, {'text': 'Send invites', 'is_completed': False}, - {'text': 'Clean house', 'is_completed': False} + {'text': 'Clean house', 'is_completed': False} } } @@ -44,4 +44,4 @@ Let's take a look at updating our nested one-to-many data structure. ### Making PATCH requests -[cite]: http://jsonapi.org/format/#url-based-json-api \ No newline at end of file +[cite]: http://jsonapi.org/format/#url-based-json-api diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index db5b9ea7b..f9027b688 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -134,7 +134,7 @@ A serializer class is very similar to a Django `Form` class, and includes simila The field flags can also control how the serializer should be displayed in certain circumstances, such as when rendering to HTML. The `style={'type': 'textarea'}` flag above is equivelent to using `widget=widgets.Textarea` on a Django `Form` class. This is particularly useful for controlling how the browsable API should be displayed, as we'll see later in the tutorial. -We can actually also save ourselves some time by using the `ModelSerializer` class, as we'll see later, but for now we'll keep our serializer definition explicit. +We can actually also save ourselves some time by using the `ModelSerializer` class, as we'll see later, but for now we'll keep our serializer definition explicit. ## Working with Serializers From b8aa7e0c34dc839a47b679aa2402d0f1b98704a0 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Tue, 18 Nov 2014 17:16:54 +0000 Subject: [PATCH 27/47] Fix previous and next links --- docs_theme/nav.html | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs_theme/nav.html b/docs_theme/nav.html index 87e197b35..0f3b9871c 100644 --- a/docs_theme/nav.html +++ b/docs_theme/nav.html @@ -2,8 +2,12 @@
    GitHub - Next - Previous + + Search From 8677316959c65da1305b0bfc7c06733093d5af3e Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Tue, 18 Nov 2014 17:20:42 +0000 Subject: [PATCH 28/47] Disable prev and next links --- docs_theme/nav.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs_theme/nav.html b/docs_theme/nav.html index 0f3b9871c..e6ab01bad 100644 --- a/docs_theme/nav.html +++ b/docs_theme/nav.html @@ -2,10 +2,10 @@
    GitHub - - Search From 6f28adeefe21df4330fe70bc20cb457e249a29d2 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 19 Nov 2014 08:56:14 +0000 Subject: [PATCH 29/47] Added nicer page titles --- mkdocs.yml | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index c70de9822..d5feab65c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,12 +7,12 @@ repo_url: https://github.com/tomchristie/django-rest-framework pages: - ['index.md', ] - ['tutorial/quickstart.md', ] - - ['tutorial/1-serialization.md', ] - - ['tutorial/2-requests-and-responses.md', ] - - ['tutorial/3-class-based-views.md', ] - - ['tutorial/4-authentication-and-permissions.md', ] - - ['tutorial/5-relationships-and-hyperlinked-apis.md', ] - - ['tutorial/6-viewsets-and-routers.md', ] + - ['tutorial/1-serialization.md', "Tutorial", "1 - Serialization"] + - ['tutorial/2-requests-and-responses.md', "Tutorial", "2 - Requests and responses"] + - ['tutorial/3-class-based-views.md', "Tutorial", "3 - Class based views"] + - ['tutorial/4-authentication-and-permissions.md', "Tutorial", "4 - Authentication and permissions"] + - ['tutorial/5-relationships-and-hyperlinked-apis.md', "Tutorial", "5 - Relationships and hyperlinked APIs"] + - ['tutorial/6-viewsets-and-routers.md', "Tutorial", "6- Viewsets and routers"] - ['api-guide/requests.md', 'API Guide', ] - ['api-guide/responses.md', 'API Guide', ] - ['api-guide/views.md', 'API Guide', ] @@ -22,8 +22,8 @@ pages: - ['api-guide/parsers.md', 'API Guide', ] - ['api-guide/renderers.md', 'API Guide', ] - ['api-guide/serializers.md', 'API Guide', ] - - ['api-guide/fields.md', 'API Guide', ] - - ['api-guide/relations.md', 'API Guide', ] + - ['api-guide/fields.md', 'API Guide', "Serializer fields"] + - ['api-guide/relations.md', 'API Guide', "Serializer relations"] - ['api-guide/validators.md', 'API Guide', ] - ['api-guide/authentication.md', 'API Guide', ] - ['api-guide/permissions.md', 'API Guide', ] @@ -32,25 +32,25 @@ pages: - ['api-guide/pagination.md', 'API Guide', ] - ['api-guide/content-negotiation.md', 'API Guide', ] - ['api-guide/format-suffixes.md', 'API Guide', ] - - ['api-guide/reverse.md', 'API Guide', ] + - ['api-guide/reverse.md', 'API Guide', 'Returning URLs'] - ['api-guide/exceptions.md', 'API Guide', ] - ['api-guide/status-codes.md', 'API Guide', ] - ['api-guide/testing.md', 'API Guide', ] - ['api-guide/settings.md', 'API Guide', ] - - ['topics/documenting-your-api.md', ] - - ['topics/ajax-csrf-cors.md', ] - - ['topics/browser-enhancements.md', ] - - ['topics/browsable-api.md', ] - - ['topics/rest-hypermedia-hateoas.md', ] - - ['topics/third-party-resources.md', ] - - ['topics/contributing.md', ] - - ['topics/rest-framework-2-announcement.md', ] - - ['topics/2.2-announcement.md', ] - - ['topics/2.3-announcement.md', ] - - ['topics/2.4-announcement.md', ] - - ['topics/kickstarter-announcement.md', ] - - ['topics/release-notes.md', ] - - ['topics/credits.md', ] + - ['topics/documenting-your-api.md', 'Topics', 'Documenting your API'] + - ['topics/ajax-csrf-cors.md', 'Topics', 'AJAX, CSRF & CORS'] + - ['topics/browser-enhancements.md', 'Topics',] + - ['topics/browsable-api.md', 'Topics', 'The Browsable API'] + - ['topics/rest-hypermedia-hateoas.md', 'Topics', 'REST, Hypermedia & HATEOAS'] + - ['topics/third-party-resources.md', 'Topics', 'Third Party Resources'] + - ['topics/contributing.md', 'Topics', 'Contributing to REST framework'] + - ['topics/rest-framework-2-announcement.md', 'Topics', '2.0 Announcement'] + - ['topics/2.2-announcement.md', 'Topics', '2.2 Announcement'] + - ['topics/2.3-announcement.md', 'Topics', '2.3 Announcement'] + - ['topics/2.4-announcement.md', 'Topics', '2.4 Announcement'] + - ['topics/kickstarter-announcement.md', 'Topics', 'Kickstarter Announcement'] + - ['topics/release-notes.md', 'Topics', 'Release Notes'] + - ['topics/credits.md', 'Topics', 'Credits'] site_dir: html theme_dir: docs_theme From df33538f141f5d5d4a9f905a56cad0f881fb20de Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 19 Nov 2014 12:41:58 +0000 Subject: [PATCH 30/47] Make the quotes consistent --- mkdocs.yml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index d5feab65c..925586d19 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,12 +7,12 @@ repo_url: https://github.com/tomchristie/django-rest-framework pages: - ['index.md', ] - ['tutorial/quickstart.md', ] - - ['tutorial/1-serialization.md', "Tutorial", "1 - Serialization"] - - ['tutorial/2-requests-and-responses.md', "Tutorial", "2 - Requests and responses"] - - ['tutorial/3-class-based-views.md', "Tutorial", "3 - Class based views"] - - ['tutorial/4-authentication-and-permissions.md', "Tutorial", "4 - Authentication and permissions"] - - ['tutorial/5-relationships-and-hyperlinked-apis.md', "Tutorial", "5 - Relationships and hyperlinked APIs"] - - ['tutorial/6-viewsets-and-routers.md', "Tutorial", "6- Viewsets and routers"] + - ['tutorial/1-serialization.md', 'Tutorial', '1 - Serialization'] + - ['tutorial/2-requests-and-responses.md', 'Tutorial', '2 - Requests and responses'] + - ['tutorial/3-class-based-views.md', 'Tutorial', '3 - Class based views'] + - ['tutorial/4-authentication-and-permissions.md', 'Tutorial', '4 - Authentication and permissions'] + - ['tutorial/5-relationships-and-hyperlinked-apis.md', 'Tutorial', '5 - Relationships and hyperlinked APIs'] + - ['tutorial/6-viewsets-and-routers.md', 'Tutorial', '6- Viewsets and routers'] - ['api-guide/requests.md', 'API Guide', ] - ['api-guide/responses.md', 'API Guide', ] - ['api-guide/views.md', 'API Guide', ] @@ -22,8 +22,8 @@ pages: - ['api-guide/parsers.md', 'API Guide', ] - ['api-guide/renderers.md', 'API Guide', ] - ['api-guide/serializers.md', 'API Guide', ] - - ['api-guide/fields.md', 'API Guide', "Serializer fields"] - - ['api-guide/relations.md', 'API Guide', "Serializer relations"] + - ['api-guide/fields.md', 'API Guide', 'Serializer fields'] + - ['api-guide/relations.md', 'API Guide', 'Serializer relations'] - ['api-guide/validators.md', 'API Guide', ] - ['api-guide/authentication.md', 'API Guide', ] - ['api-guide/permissions.md', 'API Guide', ] @@ -54,5 +54,5 @@ pages: site_dir: html theme_dir: docs_theme -copyright: Copyright © 2014, Tom Christie. +copyright: Copyright © 2014, Tom Christie. google_analytics: ['UA-18852272-2', 'django-rest-framework.org'] From 5a6bdd01ba9f8731c0963c355b41839860a5a4de Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 19 Nov 2014 15:59:25 +0000 Subject: [PATCH 31/47] Highlight H1's in the TOC --- docs_theme/base.html | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs_theme/base.html b/docs_theme/base.html index 544e21881..02be73ee8 100644 --- a/docs_theme/base.html +++ b/docs_theme/base.html @@ -106,12 +106,21 @@
      {% for toc_item in toc %} -
    • {{ toc_item.title }} -
      • - {% for toc_item in toc_item.children %} -
    • {{ toc_item.title }} -
      • - {% endfor %} {% endfor %} {# TODO: This is a bit of a hack. We don't want to refer to the file specifically. #} {% if current_page.input_path == 'index.md' %} + +
    • + {{ toc_item.title }} +
      • + + {% for toc_item in toc_item.children %} +
    • + {{ toc_item.title }} +
      • + {% endfor %} + + {% endfor %} + + {# TODO: This is a bit of a hack. We don't want to refer to the file specifically. #} + {% if current_page.input_path == 'index.md' %}
      From deb2bb4376600187c881f91791c278d9486ea8d9 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 19 Nov 2014 16:15:47 +0000 Subject: [PATCH 32/47] Add Home link to the theme --- docs_theme/nav.html | 1 + 1 file changed, 1 insertion(+) diff --git a/docs_theme/nav.html b/docs_theme/nav.html index e6ab01bad..622cb33bf 100644 --- a/docs_theme/nav.html +++ b/docs_theme/nav.html @@ -19,6 +19,7 @@ {% if include_nav %}
        +
      • Home
        • {% for nav_item in nav %} {% if nav_item.children %}
      • {{ nav_item.title }} From a0c12bf7c5cf96fbbdf0a0eb12702a093ccd3a51 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 19 Nov 2014 16:22:23 +0000 Subject: [PATCH 33/47] Change the background of the selected page on the dropdown --- docs/css/default.css | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/css/default.css b/docs/css/default.css index 7f3acfed2..8c9cd5363 100644 --- a/docs/css/default.css +++ b/docs/css/default.css @@ -181,7 +181,7 @@ body{ } .navbar .navbar-inner .nav li, .navbar .navbar-inner .nav li a, .navbar .navbar-inner .brand{ - color: white; + color: white; } .nav-list > .active > a, .navbar .navbar-inner .nav li a:hover { @@ -190,8 +190,20 @@ body{ } .navbar .navbar-inner .dropdown-menu li a, .navbar .navbar-inner .dropdown-menu li{ - color: #A30000; + color: #A30000; } + +.dropdown-menu .active > a, +.dropdown-menu .active > a:hover { + background-image: none; +} + +.navbar-inverse .nav .dropdown .active > a, +.navbar-inverse .nav .dropdown .active > a:hover, +.navbar-inverse .nav .dropdown .active > a:focus { + background-color: #eeeeee; +} + .navbar .navbar-inner .dropdown-menu li a:hover{ background: #eeeeee; color: #c20000; From f2d4e51aaa33edf35921c459327b0a0ba2526ced Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 19 Nov 2014 16:22:39 +0000 Subject: [PATCH 34/47] Mark the homepage as active when visited --- docs_theme/nav.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs_theme/nav.html b/docs_theme/nav.html index 622cb33bf..84982ff31 100644 --- a/docs_theme/nav.html +++ b/docs_theme/nav.html @@ -19,7 +19,7 @@ {% if include_nav %}
          -
        • Home
          • +
        • Home
          • {% for nav_item in nav %} {% if nav_item.children %}
        • {{ nav_item.title }} From aa1a844154e96719c9a91f604286eb0f436f32ea Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Tue, 25 Nov 2014 13:05:48 +0000 Subject: [PATCH 35/47] Add The title to the top of the TOC for the home page --- docs_theme/base.html | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs_theme/base.html b/docs_theme/base.html index 02be73ee8..228b0ba4f 100644 --- a/docs_theme/base.html +++ b/docs_theme/base.html @@ -105,6 +105,13 @@ -->
            + + {% if current_page.input_path == 'index.md' %} +
          • + Django REST framework +
            • + {% endif %} + {% for toc_item in toc %}
          • From 935d94c034b63cbe699d5d0ef04f472c3aeb3237 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Tue, 25 Nov 2014 13:07:35 +0000 Subject: [PATCH 36/47] Don't add main to the top level items on the home page --- docs_theme/base.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs_theme/base.html b/docs_theme/base.html index 228b0ba4f..004fbacd1 100644 --- a/docs_theme/base.html +++ b/docs_theme/base.html @@ -114,7 +114,7 @@ {% for toc_item in toc %} -
          • +
          • {{ toc_item.title }}
            • From 4d28a0930995a3a73860d6a2d405e12abbf5d653 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Tue, 25 Nov 2014 13:09:47 +0000 Subject: [PATCH 37/47] Refer to the current_page title rather than filename --- docs_theme/base.html | 11 ++++------- docs_theme/nav.html | 2 +- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/docs_theme/base.html b/docs_theme/base.html index 004fbacd1..cefaef484 100644 --- a/docs_theme/base.html +++ b/docs_theme/base.html @@ -54,9 +54,7 @@ } -{# TODO: This is a bit of a hack. We don't want to refer to the file specifically. #} - - +
            @@ -106,7 +104,7 @@
              - {% if current_page.input_path == 'index.md' %} + {% if current_page.title == 'Home' %}
            • Django REST framework
              • @@ -114,7 +112,7 @@ {% for toc_item in toc %} -
            • +
            • {{ toc_item.title }}
              • @@ -126,8 +124,7 @@ {% endfor %} - {# TODO: This is a bit of a hack. We don't want to refer to the file specifically. #} - {% if current_page.input_path == 'index.md' %} + {% if current_page.title == 'Home' %}
              diff --git a/docs_theme/nav.html b/docs_theme/nav.html index 84982ff31..24304b8a8 100644 --- a/docs_theme/nav.html +++ b/docs_theme/nav.html @@ -19,7 +19,7 @@ {% if include_nav %}
                -
              • Home
                • +
              • Home
                • {% for nav_item in nav %} {% if nav_item.children %}
              • {{ nav_item.title }} From 673f48242f34ee6b7ba91ab4cf8a67f1bb26a272 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Tue, 25 Nov 2014 13:11:30 +0000 Subject: [PATCH 38/47] Remove commented out title --- docs/index.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6288efa3c..ca10befe3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,9 +26,6 @@ Django REST Framework

                - Django REST framework is a powerful and flexible toolkit that makes it easy to build Web APIs. From 66fc51de5c4622073e7e6cfd12cc7c4a1a8ba60c Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Tue, 25 Nov 2014 13:14:51 +0000 Subject: [PATCH 39/47] Use the is_homepage property. --- docs_theme/base.html | 8 ++++---- docs_theme/nav.html | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs_theme/base.html b/docs_theme/base.html index cefaef484..6bfccab26 100644 --- a/docs_theme/base.html +++ b/docs_theme/base.html @@ -54,7 +54,7 @@ } - +
                @@ -104,7 +104,7 @@
                  - {% if current_page.title == 'Home' %} + {% if current_page.is_homepage %}
                • Django REST framework
                  • @@ -112,7 +112,7 @@ {% for toc_item in toc %} -
                • +
                • {{ toc_item.title }}
                  • @@ -124,7 +124,7 @@ {% endfor %} - {% if current_page.title == 'Home' %} + {% if current_page.is_homepage %}
                  diff --git a/docs_theme/nav.html b/docs_theme/nav.html index 24304b8a8..ca1afc0ec 100644 --- a/docs_theme/nav.html +++ b/docs_theme/nav.html @@ -19,7 +19,7 @@ {% if include_nav %}
                    -
                  • Home
                    • +
                  • Home
                    • {% for nav_item in nav %} {% if nav_item.children %}
                  • {{ nav_item.title }} From e1b8412eed18e305d7b6338a133b7f6a1270184c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Padilla?= Date: Tue, 25 Nov 2014 09:22:29 -0400 Subject: [PATCH 40/47] Add markdown and PyYAML to tox test requirements --- tox.ini | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tox.ini b/tox.ini index a7200a3f3..b33c07002 100644 --- a/tox.ini +++ b/tox.ini @@ -23,6 +23,8 @@ deps = pytest-django==2.6.1 django-filter==0.7 defusedxml==0.3 + markdown>=2.1.0 + PyYAML>=3.10 [testenv:py27-flake8] deps = From 38fe2c9dad89e58c97aad26fa16d91dddf377ddd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jose=CC=81=20Padilla?= Date: Tue, 25 Nov 2014 09:36:57 -0400 Subject: [PATCH 41/47] Document writing third party packages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the following sections: - “About Third Party Packages” - “How to create a Third Party Package” - “Existing Third Party Packages” Resolve #2043 --- docs/topics/third-party-resources.md | 332 +++++++++++++++++++++++---- 1 file changed, 281 insertions(+), 51 deletions(-) diff --git a/docs/topics/third-party-resources.md b/docs/topics/third-party-resources.md index 0317dd64c..d6a4346e3 100644 --- a/docs/topics/third-party-resources.md +++ b/docs/topics/third-party-resources.md @@ -1,92 +1,322 @@ # Third Party Resources +## About Third Party Packages + +Third Party Packages allow developers to share code that extends the functionality of Django REST framework, in order to support additional use-cases. + +We **support**, **encourage** and **strongly favour** the creation of Third Party Packages to encapsulate new behaviour rather than adding additional functionality directly to Django REST Framework. + +We aim to make creating Third Party Packages as easy as possible, whilst keeping the **simplicity** of the core API and ensuring that **maintainance** of the main project remains under control. If a Third Party Package proves popular it is relatively easy to move it into the main project; removing features is much more problematic. + +If you have an idea for a new feature please consider how it may be packaged as a Third Party Package. We're always happy to dicuss ideas on the [Mailing List][discussion-group]. + +## How to create a Third Party Package + +### Creating your package + +You can use [this cookiecutter template][cookiecutter] for creating reusable Django REST Framework packages quickly. Cookiecutter creates projects from project templates. While optional, this cookiecutter template includes best practices from Django REST framework and other packages, as well as a Travis CI configuration, Tox configuration, and a sane setup.py for easy PyPI registration/distribution. + +Note: Let us know if you have an alternate cookiecuter package so we can also link to it. + +#### Running the initial cookiecutter command + +To run the initial cookiecutter command, you'll first need to install the Python `cookiecutter` package. + + $ pip install cookiecutter + +Once `cookiecutter` is installed just run the following to create a new project. + + $ cookiecutter gh:jpadilla/cookiecutter-django-rest-framework + +You'll be prompted for some questions, answer them, then it'll create your Python package in the current working directory based on those values. + + full_name (default is "Your full name here")? Johnny Appleseed + email (default is "you@example.com")? jappleseed@example.com + github_username (default is "yourname")? jappleseed + pypi_project_name (default is "dj-package")? djangorestframework-custom-auth + repo_name (default is "dj-package")? django-rest-framework-custom-auth + app_name (default is "djpackage")? custom_auth + project_short_description (default is "Your project description goes here")? + year (default is "2014")? + version (default is "0.1.0")? + +#### Getting it onto GitHub + +To put your project up on GitHub, you'll need a repository for it to live in. You can create a new repository [here][new-repo]. If you need help, check out the [Create A Repo][create-a-repo] article on GitHub. + + +#### Adding to Travis CI + +We recommend using [Travis CI][travis-ci], a hosted continuous integration service which integrates well with GitHub and is free for public repositories. + +To get started with Travis CI, [sign in][travis-ci] with your GitHub account. Once you're signed in, go to your [profile page][travis-profile] and enable the service hook for the repository you want. + +If you use the cookiecutter template, your project will already contain a `.travis.yml` file which Travis CI will use to build your project and run tests. By default, builds are triggered everytime you push to your repository or create Pull Request. + +#### Uploading to PyPI + +Once you've got at least a prototype working and tests running, you should publish it on PyPI to allow others to install it via `pip`. + +You must [register][pypi-register] an account before publishing to PyPI. + +To register your package on PyPI run the following command. + + $ python setup.py register + +If this is the first time publishing to PyPI, you'll be prompted to login. + +Note: Before publishing you'll need to make sure you have the latest pip that supports `wheel` as well as install the `wheel` package. + + $ pip install --upgrade pip + $ pip install wheel + +After this, every time you want to release a new version on PyPI just run the following command. + + $ python setup.py publish + You probably want to also tag the version now: + git tag -a {0} -m 'version 0.1.0' + git push --tags + +After releasing a new version to PyPI, it's always a good idea to tag the version and make available as a GitHub Release. + +We recommend to follow [Semantic Versioning][semver] for your package's versions. + +### Development + +#### Version requirements + +The cookiecutter template assumes a set of supported versions will be provided for Python and Django. Make sure you correctly update your requirements, docs, `tox.ini`, `.travis.yml`, and `setup.py` to match the set of versions you wish to support. + +#### Tests + +The cookiecutter template includes a `runtests.py` which uses the `pytest` package as a test runner. + +Before running, you'll need to install a couple test requirements. + + $ pip install -r requirements-test.txt + +Once requirements installed, you can run `runtests.py`. + + $ ./runtests.py + +Run using a more concise output style. + + $ ./runtests.py -q + +Run the tests using a more concise output style, no coverage, no flake8. + + $ ./runtests.py --fast + +Don't run the flake8 code linting. + + $ ./runtests.py --nolint + +Only run the flake8 code linting, don't run the tests. + + $ ./runtests.py --lintonly + +Run the tests for a given test case. + + $ ./runtests.py MyTestCase + +Run the tests for a given test method. + + $ ./runtests.py MyTestCase.test_this_method + +Shorter form to run the tests for a given test method. + + $ ./runtests.py test_this_method + +To run your tests against multiple versions of Python as different versions of requirements such as Django we recommend using `tox`. [Tox][tox-docs] is a generic virtualenv management and test command line tool. + +First, install `tox` globally. + + $ pip install tox + +To run `tox`, just simply run: + + $ tox + +To run a particular `tox` environment: + + $ tox -e envlist + +`envlist` is a comma-separated value to that specifies the environments to run tests against. To view a list of all possible test environments, run: + + $ tox -l + +#### Version compatibility + +Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries, you'll need to run slightly different code depending on the environment. Any code that branches in this way should be isolated into a `compat.py` module, and should provide a single common interface that the rest of the codebase can use. + +Check out Django REST framework's [compat.py][drf-compat] for an example. + +### Once your package is available + +Once your package is decently documented and available on PyPI, you might want share it with others that might find it useful. + +#### Adding to the Django REST framework grid + +We suggest adding your package to the [REST Framework][rest-framework-grid] grid on Django Packages. + +#### Adding to the Django REST framework docs + +Create a [Pull Request][drf-create-pr] or [Issue][drf-create-issue] on GitHub, and we'll add a link to it from the main REST framework documentation. You can add your package under **Third party packages** of the API Guide section that best applies, like [Authentication][authentication] or [Permissions][permissions]. You can also link your package under the [Third Party Resources][third-party-resources] section. + +#### Announce on the discussion group. + +You can also let others know about your package through the [discussion group][discussion-group]. + +## Existing Third Party Packages + Django REST Framework has a growing community of developers, packages, and resources. -Check out a grid detailing all the packages and ecosystem around Django REST Framework at [Django Packages](https://www.djangopackages.com/grids/g/django-rest-framework/). +Check out a grid detailing all the packages and ecosystem around Django REST Framework at [Django Packages][rest-framework-grid]. -To submit new content, [open an issue](https://github.com/tomchristie/django-rest-framework/issues/new) or [create a pull request](https://github.com/tomchristie/django-rest-framework/). - -## Libraries and Extensions +To submit new content, [open an issue][drf-create-issue] or [create a pull request][drf-create-pr]. ### Authentication -* [djangorestframework-digestauth](https://github.com/juanriaza/django-rest-framework-digestauth) - Provides Digest Access Authentication support. -* [django-oauth-toolkit](https://github.com/evonove/django-oauth-toolkit) - Provides OAuth 2.0 support. -* [doac](https://github.com/Rediker-Software/doac) - Provides OAuth 2.0 support. -* [djangorestframework-jwt](https://github.com/GetBlimp/django-rest-framework-jwt) - Provides JSON Web Token Authentication support. -* [hawkrest](https://github.com/kumar303/hawkrest) - Provides Hawk HTTP Authorization. -* [djangorestframework-httpsignature](https://github.com/etoccalino/django-rest-framework-httpsignature) - Provides an easy to use HTTP Signature Authentication mechanism. -* [djoser](https://github.com/sunscrapers/djoser) - Provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation. +* [djangorestframework-digestauth][djangorestframework-digestauth] - Provides Digest Access Authentication support. +* [django-oauth-toolkit][django-oauth-toolkit] - Provides OAuth 2.0 support. +* [doac][doac] - Provides OAuth 2.0 support. +* [djangorestframework-jwt][djangorestframework-jwt] - Provides JSON Web Token Authentication support. +* [hawkrest][hawkrest] - Provides Hawk HTTP Authorization. +* [djangorestframework-httpsignature][djangorestframework-httpsignature] - Provides an easy to use HTTP Signature Authentication mechanism. +* [djoser][djoser] - Provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation. ### Permissions -* [drf-any-permissions](https://github.com/kevin-brown/drf-any-permissions) - Provides alternative permission handling. -* [djangorestframework-composed-permissions](https://github.com/niwibe/djangorestframework-composed-permissions) - Provides a simple way to define complex permissions. -* [rest_condition](https://github.com/caxap/rest_condition) - Another extension for building complex permissions in a simple and convenient way. +* [drf-any-permissions][drf-any-permissions] - Provides alternative permission handling. +* [djangorestframework-composed-permissions][djangorestframework-composed-permissions] - Provides a simple way to define complex permissions. +* [rest_condition][rest-condition] - Another extension for building complex permissions in a simple and convenient way. ### Serializers -* [django-rest-framework-mongoengine](https://github.com/umutbozkurt/django-rest-framework-mongoengine) - Serializer class that supports using MongoDB as the storage layer for Django REST framework. -* [djangorestframework-gis](https://github.com/djangonauts/django-rest-framework-gis) - Geographic add-ons -* [djangorestframework-hstore](https://github.com/djangonauts/django-rest-framework-hstore) - Serializer class to support django-hstore DictionaryField model field and its schema-mode feature. +* [django-rest-framework-mongoengine][django-rest-framework-mongoengine] - Serializer class that supports using MongoDB as the storage layer for Django REST framework. +* [djangorestframework-gis][djangorestframework-gis] - Geographic add-ons +* [djangorestframework-hstore][djangorestframework-hstore] - Serializer class to support django-hstore DictionaryField model field and its schema-mode feature. ### Serializer fields -* [drf-compound-fields](https://github.com/estebistec/drf-compound-fields) - Provides "compound" serializer fields, such as lists of simple values. -* [django-extra-fields](https://github.com/Hipo/drf-extra-fields) - Provides extra serializer fields. +* [drf-compound-fields][drf-compound-fields] - Provides "compound" serializer fields, such as lists of simple values. +* [django-extra-fields][django-extra-fields] - Provides extra serializer fields. ### Views -* [djangorestframework-bulk](https://github.com/miki725/django-rest-framework-bulk) - Implements generic view mixins as well as some common concrete generic views to allow to apply bulk operations via API requests. +* [djangorestframework-bulk][djangorestframework-bulk] - Implements generic view mixins as well as some common concrete generic views to allow to apply bulk operations via API requests. ### Routers -* [drf-nested-routers](https://github.com/alanjds/drf-nested-routers) - Provides routers and relationship fields for working with nested resources. -* [wq.db.rest](http://wq.io/docs/about-rest) - Provides an admin-style model registration API with reasonable default URLs and viewsets. +* [drf-nested-routers][drf-nested-routers] - Provides routers and relationship fields for working with nested resources. +* [wq.db.rest][wq.db.rest] - Provides an admin-style model registration API with reasonable default URLs and viewsets. ### Parsers -* [djangorestframework-msgpack](https://github.com/juanriaza/django-rest-framework-msgpack) - Provides MessagePack renderer and parser support. -* [djangorestframework-camel-case](https://github.com/vbabiy/djangorestframework-camel-case) - Provides camel case JSON renderers and parsers. +* [djangorestframework-msgpack][djangorestframework-msgpack] - Provides MessagePack renderer and parser support. +* [djangorestframework-camel-case][djangorestframework-camel-case] - Provides camel case JSON renderers and parsers. ### Renderers -* [djangorestframework-csv](https://github.com/mjumbewu/django-rest-framework-csv) - Provides CSV renderer support. -* [drf_ujson](https://github.com/gizmag/drf-ujson-renderer) - Implements JSON rendering using the UJSON package. -* [Django REST Pandas](https://github.com/wq/django-rest-pandas) - Pandas DataFrame-powered renderers including Excel, CSV, and SVG formats. +* [djangorestframework-csv][djangorestframework-csv] - Provides CSV renderer support. +* [drf_ujson][drf_ujson] - Implements JSON rendering using the UJSON package. +* [rest-pandas][rest-pandas] - Pandas DataFrame-powered renderers including Excel, CSV, and SVG formats. ### Filtering -* [djangorestframework-chain](https://github.com/philipn/django-rest-framework-chain) - Allows arbitrary chaining of both relations and lookup filters. +* [djangorestframework-chain][djangorestframework-chain] - Allows arbitrary chaining of both relations and lookup filters. ### Misc -* [djangorestrelationalhyperlink](https://github.com/fredkingham/django_rest_model_hyperlink_serializers_project) - A hyperlinked serialiser that can can be used to alter relationships via hyperlinks, but otherwise like a hyperlink model serializer. -* [django-rest-swagger](https://github.com/marcgibbons/django-rest-swagger) - An API documentation generator for Swagger UI. -* [django-rest-framework-proxy ](https://github.com/eofs/django-rest-framework-proxy) - Proxy to redirect incoming request to another API server. -* [gaiarestframework](https://github.com/AppsFuel/gaiarestframework) - Utils for django-rest-framewok -* [drf-extensions](https://github.com/chibisov/drf-extensions) - A collection of custom extensions -* [ember-data-django-rest-adapter](https://github.com/toranb/ember-data-django-rest-adapter) - An ember-data adapter +* [djangorestrelationalhyperlink][djangorestrelationalhyperlink] - A hyperlinked serialiser that can can be used to alter relationships via hyperlinks, but otherwise like a hyperlink model serializer. +* [django-rest-swagger][django-rest-swagger] - An API documentation generator for Swagger UI. +* [django-rest-framework-proxy][django-rest-framework-proxy] - Proxy to redirect incoming request to another API server. +* [gaiarestframework][gaiarestframework] - Utils for django-rest-framewok +* [drf-extensions][drf-extensions] - A collection of custom extensions +* [ember-data-django-rest-adapter][ember-data-django-rest-adapter] - An ember-data adapter -## Tutorials +## Other Resources -* [Beginner's Guide to the Django Rest Framework](http://code.tutsplus.com/tutorials/beginners-guide-to-the-django-rest-framework--cms-19786) -* [Getting Started with Django Rest Framework and AngularJS](http://blog.kevinastone.com/getting-started-with-django-rest-framework-and-angularjs.html) -* [End to end web app with Django-Rest-Framework & AngularJS](http://blog.mourafiq.com/post/55034504632/end-to-end-web-app-with-django-rest-framework) -* [Start Your API - django-rest-framework part 1](https://godjango.com/41-start-your-api-django-rest-framework-part-1/) -* [Permissions & Authentication - django-rest-framework part 2](https://godjango.com/43-permissions-authentication-django-rest-framework-part-2/) -* [ViewSets and Routers - django-rest-framework part 3](https://godjango.com/45-viewsets-and-routers-django-rest-framework-part-3/) -* [Django Rest Framework User Endpoint](http://richardtier.com/2014/02/25/django-rest-framework-user-endpoint/) -* [Check credentials using Django Rest Framework](http://richardtier.com/2014/03/06/110/) +### Tutorials -## Videos +* [Beginner's Guide to the Django Rest Framework][beginners-guide-to-the-django-rest-framework] +* [Getting Started with Django Rest Framework and AngularJS][getting-started-with-django-rest-framework-and-angularjs] +* [End to end web app with Django-Rest-Framework & AngularJS][end-to-end-web-app-with-django-rest-framework-angularjs] +* [Start Your API - django-rest-framework part 1][start-your-api-django-rest-framework-part-1] +* [Permissions & Authentication - django-rest-framework part 2][permissions-authentication-django-rest-framework-part-2] +* [ViewSets and Routers - django-rest-framework part 3][viewsets-and-routers-django-rest-framework-part-3] +* [Django Rest Framework User Endpoint][django-rest-framework-user-endpoint] +* [Check credentials using Django Rest Framework][check-credentials-using-django-rest-framework] -* [Ember and Django Part 1 (Video)](http://www.neckbeardrepublic.com/screencasts/ember-and-django-part-1) -* [Django Rest Framework Part 1 (Video)](http://www.neckbeardrepublic.com/screencasts/django-rest-framework-part-1) -* [Pyowa July 2013 - Django Rest Framework (Video)](http://www.youtube.com/watch?v=E1ZrehVxpBo) -* [django-rest-framework and angularjs (Video)](http://www.youtube.com/watch?v=Q8FRBGTJ020) +### Videos -## Articles +* [Ember and Django Part 1 (Video)][ember-and-django-part 1-video] +* [Django Rest Framework Part 1 (Video)][django-rest-framework-part-1-video] +* [Pyowa July 2013 - Django Rest Framework (Video)][pyowa-july-2013-django-rest-framework-video] +* [django-rest-framework and angularjs (Video)][django-rest-framework-and-angularjs-video] -* [Web API performance: profiling Django REST framework](http://dabapps.com/blog/api-performance-profiling-django-rest-framework/) -* [API Development with Django and Django REST Framework](https://bnotions.com/api-development-with-django-and-django-rest-framework/) +### Articles + +* [Web API performance: profiling Django REST framework][web-api-performance-profiling-django-rest-framework] +* [API Development with Django and Django REST Framework][api-development-with-django-and-django-rest-framework] + + +[cookiecutter]: https://github.com/jpadilla/cookiecutter-django-rest-framework +[new-repo]: https://github.com/new +[create-a-repo]: https://help.github.com/articles/create-a-repo/ +[travis-ci]: https://travis-ci.org +[travis-profile]: https://travis-ci.org/profile +[pypi-register]: https://pypi.python.org/pypi?%3Aaction=register_form +[semver]: http://semver.org/ +[tox-docs]: https://tox.readthedocs.org/en/latest/ +[drf-compat]: https://github.com/tomchristie/django-rest-framework/blob/master/rest_framework/compat.py +[rest-framework-grid]: https://www.djangopackages.com/grids/g/django-rest-framework/ +[drf-create-pr]: https://github.com/tomchristie/django-rest-framework/compare +[drf-create-issue]: https://github.com/tomchristie/django-rest-framework/issues/new +[authentication]: ../api-guide/authentication.md +[permissions]: ../api-guide/permissions.md +[discussion-group]: https://groups.google.com/forum/#!forum/django-rest-framework +[djangorestframework-digestauth]: https://github.com/juanriaza/django-rest-framework-digestauth +[django-oauth-toolkit]: https://github.com/evonove/django-oauth-toolkit +[doac]: https://github.com/Rediker-Software/doac +[djangorestframework-jwt]: https://github.com/GetBlimp/django-rest-framework-jwt +[hawkrest]: https://github.com/kumar303/hawkrest +[djangorestframework-httpsignature]: https://github.com/etoccalino/django-rest-framework-httpsignature +[djoser]: https://github.com/sunscrapers/djoser +[drf-any-permissions]: https://github.com/kevin-brown/drf-any-permissions +[djangorestframework-composed-permissions]: https://github.com/niwibe/djangorestframework-composed-permissions +[rest-condition]: https://github.com/caxap/rest_condition +[django-rest-framework-mongoengine]: https://github.com/umutbozkurt/django-rest-framework-mongoengine +[djangorestframework-gis]: https://github.com/djangonauts/django-rest-framework-gis +[djangorestframework-hstore]: https://github.com/djangonauts/django-rest-framework-hstore +[drf-compound-fields]: https://github.com/estebistec/drf-compound-fields +[django-extra-fields]: https://github.com/Hipo/drf-extra-fields +[djangorestframework-bulk]: https://github.com/miki725/django-rest-framework-bulk +[drf-nested-routers]: https://github.com/alanjds/drf-nested-routers +[wq.db.rest]: http://wq.io/docs/about-rest +[djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack +[djangorestframework-camel-case]: https://github.com/vbabiy/djangorestframework-camel-case +[djangorestframework-csv]: https://github.com/mjumbewu/django-rest-framework-csv +[drf_ujson]: https://github.com/gizmag/drf-ujson-renderer +[rest-pandas]: https://github.com/wq/django-rest-pandas +[djangorestframework-chain]: https://github.com/philipn/django-rest-framework-chain +[djangorestrelationalhyperlink]: https://github.com/fredkingham/django_rest_model_hyperlink_serializers_project +[django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger +[django-rest-framework-proxy]: https://github.com/eofs/django-rest-framework-proxy +[gaiarestframework]: https://github.com/AppsFuel/gaiarestframework +[drf-extensions]: https://github.com/chibisov/drf-extensions +[ember-data-django-rest-adapter]: https://github.com/toranb/ember-data-django-rest-adapter +[beginners-guide-to-the-django-rest-framework]: http://code.tutsplus.com/tutorials/beginners-guide-to-the-django-rest-framework--cms-19786 +[getting-started-with-django-rest-framework-and-angularjs]: http://blog.kevinastone.com/getting-started-with-django-rest-framework-and-angularjs.html +[end-to-end-web-app-with-django-rest-framework-angularjs]: http://blog.mourafiq.com/post/55034504632/end-to-end-web-app-with-django-rest-framework +[start-your-api-django-rest-framework-part-1]: https://godjango.com/41-start-your-api-django-rest-framework-part-1/ +[permissions-authentication-django-rest-framework-part-2]: https://godjango.com/43-permissions-authentication-django-rest-framework-part-2/ +[viewsets-and-routers-django-rest-framework-part-3]: https://godjango.com/45-viewsets-and-routers-django-rest-framework-part-3/ +[django-rest-framework-user-endpoint]: http://richardtier.com/2014/02/25/django-rest-framework-user-endpoint/ +[check-credentials-using-django-rest-framework]: http://richardtier.com/2014/03/06/110/ +[ember-and-django-part 1-video]: http://www.neckbeardrepublic.com/screencasts/ember-and-django-part-1 +[django-rest-framework-part-1-video]: http://www.neckbeardrepublic.com/screencasts/django-rest-framework-part-1 +[pyowa-july-2013-django-rest-framework-video]: http://www.youtube.com/watch?v=e1zrehvxpbo +[django-rest-framework-and-angularjs-video]: http://www.youtube.com/watch?v=q8frbgtj020 +[web-api-performance-profiling-django-rest-framework]: http://dabapps.com/blog/api-performance-profiling-django-rest-framework/ +[api-development-with-django-and-django-rest-framework]: https://bnotions.com/api-development-with-django-and-django-rest-framework/ From 64d8e3dcb6846610e1908e067962b0c8457a86f8 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 25 Nov 2014 13:50:35 +0000 Subject: [PATCH 42/47] Typo. Refs #2132. --- docs/topics/third-party-resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/third-party-resources.md b/docs/topics/third-party-resources.md index d6a4346e3..ffb490af3 100644 --- a/docs/topics/third-party-resources.md +++ b/docs/topics/third-party-resources.md @@ -6,7 +6,7 @@ Third Party Packages allow developers to share code that extends the functionali We **support**, **encourage** and **strongly favour** the creation of Third Party Packages to encapsulate new behaviour rather than adding additional functionality directly to Django REST Framework. -We aim to make creating Third Party Packages as easy as possible, whilst keeping the **simplicity** of the core API and ensuring that **maintainance** of the main project remains under control. If a Third Party Package proves popular it is relatively easy to move it into the main project; removing features is much more problematic. +We aim to make creating Third Party Packages as easy as possible, whilst keeping the **simplicity** of the core API and ensuring that **maintenance** of the main project remains under control. If a Third Party Package proves popular it is relatively easy to move it into the main project; removing features is much more problematic. If you have an idea for a new feature please consider how it may be packaged as a Third Party Package. We're always happy to dicuss ideas on the [Mailing List][discussion-group]. From 653d626b3c3189260423bec7a1dd4faed9f8708d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Padilla?= Date: Tue, 25 Nov 2014 11:33:18 -0400 Subject: [PATCH 43/47] Fix failing YAML tests --- tests/test_renderers.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/test_renderers.py b/tests/test_renderers.py index a8fd5f460..5ef65dd77 100644 --- a/tests/test_renderers.py +++ b/tests/test_renderers.py @@ -9,7 +9,7 @@ from django.test import TestCase from django.utils import six, unittest from django.utils.translation import ugettext_lazy as _ from rest_framework import status, permissions -from rest_framework.compat import yaml, etree, StringIO +from rest_framework.compat import yaml, etree, StringIO, BytesIO from rest_framework.response import Response from rest_framework.views import APIView from rest_framework.renderers import BaseRenderer, JSONRenderer, YAMLRenderer, \ @@ -467,7 +467,7 @@ if yaml: obj = {'foo': ['bar', 'baz']} renderer = YAMLRenderer() content = renderer.render(obj, 'application/yaml') - self.assertEqual(content, _yaml_repr) + self.assertEqual(content.decode('utf-8'), _yaml_repr) def test_render_and_parse(self): """ @@ -480,7 +480,7 @@ if yaml: parser = YAMLParser() content = renderer.render(obj, 'application/yaml') - data = parser.parse(StringIO(content)) + data = parser.parse(BytesIO(content)) self.assertEqual(obj, data) def test_render_decimal(self): @@ -489,7 +489,7 @@ if yaml: """ renderer = YAMLRenderer() content = renderer.render({'field': Decimal('111.2')}, 'application/yaml') - self.assertYAMLContains(content, "field: '111.2'") + self.assertYAMLContains(content.decode('utf-8'), "field: '111.2'") def assertYAMLContains(self, content, string): self.assertTrue(string in content, '%r not in %r' % (string, content)) From 929135ea58d5a41f1980d23280c6ae65bb5b3443 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 25 Nov 2014 16:01:32 +0000 Subject: [PATCH 44/47] Include CNAME file --- docs/CNAME | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/CNAME diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 000000000..4e3328996 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +www.django-rest-framework.org From 84b34d43307704ad8240b871a48dcd6e73848cd1 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 25 Nov 2014 16:06:18 +0000 Subject: [PATCH 45/47] Use default 'site' directory for docs builds --- .gitignore | 2 +- mkdocs.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index ae73f8379..2bdf8f7eb 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,7 @@ *~ .* -html/ +site/ htmlcov/ coverage/ build/ diff --git a/mkdocs.yml b/mkdocs.yml index 925586d19..f956ecf0b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,8 @@ site_description: Django REST framework - Web APIs for Django repo_url: https://github.com/tomchristie/django-rest-framework +theme_dir: docs_theme + pages: - ['index.md', ] - ['tutorial/quickstart.md', ] @@ -52,7 +54,5 @@ pages: - ['topics/release-notes.md', 'Topics', 'Release Notes'] - ['topics/credits.md', 'Topics', 'Credits'] -site_dir: html -theme_dir: docs_theme copyright: Copyright © 2014, Tom Christie. google_analytics: ['UA-18852272-2', 'django-rest-framework.org'] From c7701cd75a746a863ddf8c517a4ec9c6272d66ca Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 25 Nov 2014 16:08:48 +0000 Subject: [PATCH 46/47] Tweak --- docs/topics/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index c7991a0fe..7654136cf 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -139,7 +139,7 @@ To build the documentation, install MkDocs with `pip install mkdocs` and then ru mkdocs build -This will build the html output into the `html` directory. +This will build the documentation into the `site` directory. You can build the documentation and open a preview in a browser window by using the `serve` command. From b733f85ff1e3f70e9f5dee6f52bebe861bc0f411 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 25 Nov 2014 16:24:35 +0000 Subject: [PATCH 47/47] Minor docs tweaks --- docs/index.md | 2 +- mkdocs.yml | 49 ++++++++++++++++++++++++------------------------- 2 files changed, 25 insertions(+), 26 deletions(-) diff --git a/docs/index.md b/docs/index.md index ca10befe3..9312bb2fd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -172,7 +172,7 @@ The API guide is your complete reference manual to all the functionality provide * [Serializers][serializers] * [Serializer fields][fields] * [Serializer relations][relations] -* [Validators][validators] + * [Authentication][authentication] * [Permissions][permissions] * [Throttling][throttling] diff --git a/mkdocs.yml b/mkdocs.yml index f956ecf0b..e112315be 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,38 +7,38 @@ repo_url: https://github.com/tomchristie/django-rest-framework theme_dir: docs_theme pages: - - ['index.md', ] - - ['tutorial/quickstart.md', ] + - ['index.md', 'Home'] + - ['tutorial/quickstart.md', 'Quickstart'] - ['tutorial/1-serialization.md', 'Tutorial', '1 - Serialization'] - ['tutorial/2-requests-and-responses.md', 'Tutorial', '2 - Requests and responses'] - ['tutorial/3-class-based-views.md', 'Tutorial', '3 - Class based views'] - ['tutorial/4-authentication-and-permissions.md', 'Tutorial', '4 - Authentication and permissions'] - ['tutorial/5-relationships-and-hyperlinked-apis.md', 'Tutorial', '5 - Relationships and hyperlinked APIs'] - - ['tutorial/6-viewsets-and-routers.md', 'Tutorial', '6- Viewsets and routers'] - - ['api-guide/requests.md', 'API Guide', ] - - ['api-guide/responses.md', 'API Guide', ] - - ['api-guide/views.md', 'API Guide', ] - - ['api-guide/generic-views.md', 'API Guide', ] - - ['api-guide/viewsets.md', 'API Guide', ] - - ['api-guide/routers.md', 'API Guide', ] - - ['api-guide/parsers.md', 'API Guide', ] - - ['api-guide/renderers.md', 'API Guide', ] - - ['api-guide/serializers.md', 'API Guide', ] + - ['tutorial/6-viewsets-and-routers.md', 'Tutorial', '6 - Viewsets and routers'] + - ['api-guide/requests.md', 'API Guide', 'Requests'] + - ['api-guide/responses.md', 'API Guide', 'Responses'] + - ['api-guide/views.md', 'API Guide', 'Views'] + - ['api-guide/generic-views.md', 'API Guide', 'Generic views'] + - ['api-guide/viewsets.md', 'API Guide', 'Viewsets'] + - ['api-guide/routers.md', 'API Guide', 'Routers'] + - ['api-guide/parsers.md', 'API Guide', 'Parsers'] + - ['api-guide/renderers.md', 'API Guide', 'Renderers'] + - ['api-guide/serializers.md', 'API Guide', 'Serializers'] - ['api-guide/fields.md', 'API Guide', 'Serializer fields'] - ['api-guide/relations.md', 'API Guide', 'Serializer relations'] - - ['api-guide/validators.md', 'API Guide', ] - - ['api-guide/authentication.md', 'API Guide', ] - - ['api-guide/permissions.md', 'API Guide', ] - - ['api-guide/throttling.md', 'API Guide', ] - - ['api-guide/filtering.md', 'API Guide', ] - - ['api-guide/pagination.md', 'API Guide', ] - - ['api-guide/content-negotiation.md', 'API Guide', ] - - ['api-guide/format-suffixes.md', 'API Guide', ] +# - ['api-guide/validators.md', 'API Guide', 'Validators'] + - ['api-guide/authentication.md', 'API Guide', 'Authentication'] + - ['api-guide/permissions.md', 'API Guide', 'Permissions'] + - ['api-guide/throttling.md', 'API Guide', 'Throttling'] + - ['api-guide/filtering.md', 'API Guide', 'Filtering'] + - ['api-guide/pagination.md', 'API Guide', 'Pagination'] + - ['api-guide/content-negotiation.md', 'API Guide', 'Content negotiation'] + - ['api-guide/format-suffixes.md', 'API Guide', 'Format suffixes'] - ['api-guide/reverse.md', 'API Guide', 'Returning URLs'] - - ['api-guide/exceptions.md', 'API Guide', ] - - ['api-guide/status-codes.md', 'API Guide', ] - - ['api-guide/testing.md', 'API Guide', ] - - ['api-guide/settings.md', 'API Guide', ] + - ['api-guide/exceptions.md', 'API Guide', 'Exceptions'] + - ['api-guide/status-codes.md', 'API Guide', 'Status codes'] + - ['api-guide/testing.md', 'API Guide', 'Testing'] + - ['api-guide/settings.md', 'API Guide', 'Settings'] - ['topics/documenting-your-api.md', 'Topics', 'Documenting your API'] - ['topics/ajax-csrf-cors.md', 'Topics', 'AJAX, CSRF & CORS'] - ['topics/browser-enhancements.md', 'Topics',] @@ -54,5 +54,4 @@ pages: - ['topics/release-notes.md', 'Topics', 'Release Notes'] - ['topics/credits.md', 'Topics', 'Credits'] -copyright: Copyright © 2014, Tom Christie. google_analytics: ['UA-18852272-2', 'django-rest-framework.org']