I'm hoping to be able to comment code as I go and then have the Documentation generator produce something similar to a Javadoc hopefully sorted by type (views vs model etc).
Sphinx is good for end-user documentation. However, there's a full PEP standard for docstrings as well. Here's an old but good article on the beauty of inline documentation that's standard in Python:
http://www.electricmonk.nl/log/2008/06/22/why-python-rocks-i-inline-documentation/
Docstrings can go a long way for your development and systems teams, but be sure to check out Sphinx (and https://readthedocs.org) for more. Good luck!
If you're looking for api django documentation, we use django REST swagger where I work, it does its best to generate swagger documentation for as much of your api and models as it can. It will also read formatted comments to better the documentation. Django REST swagger is designed for the rest framework, so it would probably only work for you if you're using django-rest-framework.
Related
I'm want to write a documentation for my new module, and I was inspired by the docs of sentry.io, and I find out that they are using the Sphinx module, but the interface isn't the default one. Is there a way to change the template, or the sentry team made that for their own purposes?
Sentry has their docs open-sourced. See their documentation contributing guidelines and repository. However it is heavily modified, so you might want to start with something easier by using one of the themes that comes with Sphinx or try others.
I am a php programmer, I have built some REST based solutions in php. Now I am learning python/django. I want to make a REST based solution in Django ( only for knowledge purpose ). I do not want to use any of REST frameworks/toolkits as This project is more a exploring django/python say how they work with raw REST concept.
I searched on net, But examples/tutorial filled on already built solutions. I also checkout for request method based filtering. I am thinking of two approaches.
Either urls.py have way to check request method and transfer to respective method in views.py.
Or I can add a pre load hook/class which determine request method on application initialize, And called respective method so overriding urls.py behavior (my preferred method).
If anybody can suggest a django way to do this?
Update : I found some interesting comments on SO, like https://stackoverflow.com/a/20898410/1230744 AND https://stackoverflow.com/a/1732520/1230744. Need to check if they can have the solution, I am searching.
Well I get the answer of my questions finally from following link. It is possible through using Class based Views + serialization.
Restful routes and Django
Snippet links in side above link gave pretty much example to gave quite picture of how one can create a REST Api using only Django Core. Also I used serialize https://docs.djangoproject.com/en/dev/topics/serialization/ for Json encoding
( Now if anybody prefer, he can flag duplicate the question. ;) )
You can start from learning the code of this projects:
http://tastypieapi.org/ Tastypie
http://www.django-rest-framework.org/ Django REST framework
They are snadrd de facto for REST API for Django and their code could be a good starting point.
Also, please review this questions:
Creating a REST API for a Django application
Adding REST to Django
Django and Restful APIs
I am a newbie in Python and Django Development, I learned a lot from the easy read examples provided by the community. But recently I want to implement a customized admin filter for the admin console shipped with Django. I searched a lot and only found some out-of-date approaches to get it done. Such as:
Custom Filter in Django Admin on Django 1.3 or below
I tried to read the source code for the filters module in 'django.contrib.admin' app, but unfortunately I can hardly understand the rationale behind the codes. So I wonder whether some kind people could supply some examples or references to this issue --- How to customize admin filter in Django 1.4 ?
Thanks in advanceļ¼
There is new django.contrib.admin.SimpleListFilter introduced in v1.4 meet your need, and official document provide sample code and easy to read.
search SimpleListFilter in this section.
After some months of using Django, I feel the need to create the first my Django application. In this way I can really take the advantages of the Django's power.
Someone can give me hints and directions for learning well about it?
How Django's apps system works? And how can I create my first reusable app?
I think Django's is one of the best framework ever created and I want to learn it very well for using it in various contexts.
And now I would to take my Django's experience and skills to the next level.
In addition to the official Django documentation and tutorial, which are excellent, I would recommend two books you should check out:
Ayman Hourieh's Django Web Development 1.0:
http://www.amazon.com/gp/aw/d/1847196780/ref=redir_mdp_mobile/191-3941588-1909500
An awesome book that will take you step by step through creating your first Django app, and that touches on several of Django's features and functionality.
The Definitive Guide to Django:
http://www.amazon.com/gp/aw/d/1847196780/ref=redir_mdp_mobile/191-3941588-1909500
The title says it all, written by Django's creator and lead developer.
Don't miss a great talk about reusable apps by James Bennet: http://www.youtube.com/watch?v=A-S0tqpPga4 .
Try here for starters:
https://docs.djangoproject.com/en/1.3/intro/tutorial01/
This document describes Django 1.3.
Writing your first Django app, part 1...
And I suggest you go to Amazon.com, look through Django books and read a lot of the reviews until you find something that sounds appropriate for you.
HTH
What do you prefer when you want to "RESTify" your Django project in Django?
I came to the conclusion that there are really three options to do that:
django-piston http://bitbucket.org/jespern/django-piston/wiki/Home
django-rest-interface http://code.google.com/p/django-rest-interface/
django-restful-resources http://watchitlater.com/blog/2010/02/django-restful-resources/
Right way to do this for me would be to try all of'em and pick the one that is best for me, so meanwhile I'd like to hear yours...
Thanks.
I'm most familiar with django-piston, so I would naturally steer you in that direction.
A quick glance at the other two, though, indicates that django-rest-interface does nothing more than expose models as resources, and that django-restful-resources is some guy's one-off attempt at the same.
Piston, if I recall correctly, grew out of bitbucket.org's own site development, and allows a lot of flexibility - you can return almost any object from your resource's access methods, not just model instances, and it will be properly encoded. It also has built-in support for some nice features, like form validation (if you can get it to work right, anyway) and request throttling, among other things.
With the new class-based generic views in django 1.3 it will be super-easy to implement your own rest interface, with custom serializers and deserializers, replicating the almost complete piston's implementation using just stock code. I made a View(1.3)-based rest module in 500 lines of code, with generic RESTful resource class and sub resources, natural key support for associations, json and XML serialization and more. the module is really tailored upon my app's requirements
I did it to overcome a couple of limitations in piston's code, like having a query set modified (e.g. With .values(...)) before the handler calling .get() on it, or not being able to use a model's method in serialization.
If you do it as you need it, in a couple of days you'll have a working set of classes and mixins, that you will fully understand and be in control of.
As the "some guy" who wrote django-restful-resources I would like to clarify why it exists. It is NOT an attempt to expose models as resources, rather it is a means of allowing a single URL to be mapped to a number of different handler methods, one per HTTP verb. That's all. It can be used to expose model objects, but it can also be used to expose services as resources or anything else that you want to interact with via a single URL and HTTP verbs. If you are looking for a more full-featured solution then by all means go with Piston.
As mentioned by eternicode, django-piston is excellent. It's mature, well featured and has a good community behind it. It does seem to be lacking much ongoing development at the moment, although there is talk of a community driven fork, so that may change.
django-tastypie is also well worth a look, and seems to have a lot of impetus behind it at the moment.
I've also just released another option that's worth considering: django-rest-framework. There's a couple of really nice features behind it such as the API auto-documentation.
It uses Django 1.3's class based views, as mentioned by saverio, which means you can just drop in some of the MixIn classes it provides, without having to use the framework outright. (For example adding HTTP content negotiation for serializing output to multiple types)