Merge cbddcb21d4 into 452fd8e222

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>

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

docs/topics/documenting-your-api.md

@@ -0,0 +1,119 @@
+
+# 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()
+
+
+#### 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