From 5d9c2cb3f6f7319ffd243a7a830f00e2e4755840 Mon Sep 17 00:00:00 2001
From: Marc Gibbons <marc.gibbons@bnotions.com>
Date: Sat, 26 Jan 2013 11:12:43 -0500
Subject: [PATCH 1/4] Added a topic on documenting your API project with
 django-rest-framework-docs

---
 docs/template.html | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/template.html b/docs/template.html
index d789cc582..986bd543e 100644
--- a/docs/template.html
+++ b/docs/template.html
@@ -91,6 +91,7 @@
                 <ul class="dropdown-menu">
                   <li><a href="{{ base_url }}/topics/browser-enhancements{{ suffix }}">Browser enhancements</a></li>
                   <li><a href="{{ base_url }}/topics/browsable-api{{ suffix }}">The Browsable API</a></li>
+                  <li><a href="{{ base_url }}/topics/documenting-your-api{{ suffix }}">Documenting Your API</a></li>
                   <li><a href="{{ base_url }}/topics/rest-hypermedia-hateoas{{ suffix }}">REST, Hypermedia & HATEOAS</a></li>
                   <li><a href="{{ base_url }}/topics/rest-framework-2-announcement{{ suffix }}">2.0 Announcement</a></li>
                   <li><a href="{{ base_url }}/topics/release-notes{{ suffix }}">Release Notes</a></li>

From aab173bfa9028e88be8226c46b31b41cc9b77e90 Mon Sep 17 00:00:00 2001
From: Marc Gibbons <marc.gibbons@bnotions.com>
Date: Sat, 26 Jan 2013 11:12:58 -0500
Subject: [PATCH 2/4] Added a topic on documenting your API project with
 django-rest-framework-docs

---
 docs/topics/documenting-your-api.md | 114 ++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 docs/topics/documenting-your-api.md

diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md
new file mode 100644
index 000000000..68d3535ac
--- /dev/null
+++ b/docs/topics/documenting-your-api.md
@@ -0,0 +1,114 @@
+
+# Documenting your API
+
+> I hate to loose anything. I don't like to loose anything cause... Where is it? See that's basically the part that bothers me the most. I'm a practical guy... Where is it? "I just had it!" You know that feeling? "It was just here!" Where is it? "I don't know." It's gone.
+>
+> — George Carlin
+
+Great applications need great documentation. This is especially true for APIs built for third-party use. Some of the challenges faced with producing documentation for API are:
+
+* Laziness! Developers usually dislike writing documentation.
+* Keeping an inventory of all the endpoints. These could be scattered across multiple applications, URLs files. Generating a list, deciphering the regex pattern can be quite tedious.
+* Having the documentation reflect what the code does. What are the methods allowed, what are properties, default values, etc.
+* Keeping things updated. Making a change to your application, however minor, means going back and updating documentation.
+
+
+## Django REST Framework Docs
+
+Django REST Framework Docs attempts to facilitate the documentation process by auto-generating documentation of all your REST Framework endpoints. The documentation is generated by extracting the docstring from the API, the associated model and serializer, the allowed methods, etc. The generation is achieved on the fly, meaning that any change in your code is immediately reflected in the documentation.
+
+### Installation
+
+Install with pip
+
+`pip install django-rest-framework-docs`
+
+[Download from GitHub][source]
+
+### How to use
+
+1.  Add Django REST Framework Docs to settings.py.
+
+            INSTALLED_APPS = (
+                ...
+                'rest_framework_docs',
+            )
+
+2.  Create a new URL endpoint and include the rest_framework_docs.urls
+
+            url(r'^rest-api/documentation', include('rest_framework_docs.urls')),
+
+3.  Have a pint. Your API is now documented.
+
+
+### How it works
+The Django Rest Framework Docs scans your projects URL patterns for endpoints
+inheriting from Django Rest Framework views. It extracts comments, variables
+and methods from your code to generate documentation.
+Here is what is being tracked to generate documentation:
+
+1.  The name attribute from the URL pattern is used as the title. The following will produce a title of 'List of Countries'
+
+          url(r'^api/countries/?$', views.Countries.as_view(), name='list_of_countries'),
+
+
+2.  The class doctsring is used as the description:
+
+          class Countries(APIView):
+
+	            """
+	            This text is the description for this API
+	            """
+
+3.  The class model. (ie. User)
+
+4.  Allowed methods (`GET, POST, PUT` etc.)
+
+5.  Serializer properties. If your API uses a serializer, the properties are
+    listed
+
+6.  Custom parameters. It is possible to customize a parameter list for your
+    API. To do so, include a key-value pair in the docstring of your API class
+    delimited by two hyphens ('--').
+
+    Example: 'start_time -- The first reading':
+
+        class Countries(APIView):
+            """
+            This text is the description for this API
+                  param1 -- A first parameter
+                  param2 -- A second parameter
+            """
+
+### Customization
+
+#### Template
+Django REST Framework Docs comes with a [default Django template][template] which you may override.
+
+#### Make an API
+Another option is to create an API for documentation that can be consumed on a different platform (ie. mobile).
+
+        import json
+        from rest_framework.response import Response
+        from rest_framework.views import APIView
+        from cigar_example.restapi import urls
+        from rest_framework_docs.docs import DocumentationGenerator
+
+
+        class ApiDocumentation(APIView):
+            """
+            Gets the documentation for the API endpoints
+            """
+            def get(self, *args, **kwargs):
+                docs = DocumentationGenerator().get_docs()
+                return Response(json.loads(docs))
+
+#### Specify your own URL patterns
+By default, Django REST Framework Docs scans all your URL patterns and extracts those which inherit from the base `rest_framework.views.APIView`. You may choose to explicitly specify which URL patterns are to be included in the documentation by providing the urlpatterns to the DocumentationGenerator constructor.
+
+        from yourproject.myapp import urls
+        docs = DocumentationGenerator(urls.urlpatterns).get_docs()
+
+
+[source]: https://github.com/marcgibbons/django-rest-framework-docs
+[template]: https://github.com/marcgibbons/django-rest-framework-docs/blob/master/rest_framework_docs/templates/rest_framework_docs/docs.html

From 68e28166dd46f0c55fae9a85bbf46494c9c1c269 Mon Sep 17 00:00:00 2001
From: Marc Gibbons <marc.gibbons@bnotions.com>
Date: Sat, 26 Jan 2013 11:27:05 -0500
Subject: [PATCH 3/4] Added myself to the contributor list

---
 docs/topics/credits.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/topics/credits.md b/docs/topics/credits.md
index b033ecba5..6bdc4de0d 100644
--- a/docs/topics/credits.md
+++ b/docs/topics/credits.md
@@ -95,6 +95,7 @@ The following people have helped make REST framework great.
 * Federico Capoano - [nemesisdesign]
 * Bruno Renié - [brutasse]
 * Kevin Stone - [kevinastone]
+* Marc Gibbons - [marcgibbons]
 
 Many thanks to everyone who's contributed to the project.
 
@@ -225,3 +226,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter.
 [nemesisdesign]: https://github.com/nemesisdesign
 [brutasse]: https://github.com/brutasse
 [kevinastone]: https://github.com/kevinastone
+[marcgibbons]: https://github.com/marcgibbons
\ No newline at end of file

From cbddcb21d4ab1d6454bc854858d5d72e87527695 Mon Sep 17 00:00:00 2001
From: Marc Gibbons <marc.gibbons@bnotions.com>
Date: Sat, 26 Jan 2013 11:27:15 -0500
Subject: [PATCH 4/4] Added link at end of document to the docs github
 repository

---
 docs/topics/documenting-your-api.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md
index 68d3535ac..35a4a875f 100644
--- a/docs/topics/documenting-your-api.md
+++ b/docs/topics/documenting-your-api.md
@@ -110,5 +110,10 @@ By default, Django REST Framework Docs scans all your URL patterns and extracts
         docs = DocumentationGenerator(urls.urlpatterns).get_docs()
 
 
+#### View the docs on GitHub
+Below is the link to the Django REST Frameworks Docs repository on GitHub. An example is provided for download and includes screenshots.
+
+[https://github.com/marcgibbons/django-rest-framework-docs][source]
+
 [source]: https://github.com/marcgibbons/django-rest-framework-docs
 [template]: https://github.com/marcgibbons/django-rest-framework-docs/blob/master/rest_framework_docs/templates/rest_framework_docs/docs.html