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.
Related
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.
I am new to Django and Python and after reading a lot I decided not to use global functions as views (maybe because I am not used to global functions but mostly because I want a better reuse level and prefer to have smaller code blocks). The problem is that most of the Django apps I have been checking do not use a class based approach.
Is this because I am checking code in the wrong places (I started with the Django tutorial and then on github)?
I'm asking this because in the future I hope to be working with more Django programmers and don't want to adopt a non-standard approach at the beginning.
One fact is that class based view was added in Django 1.3, so if you're planning to support old Django version than you will have to stick with function view, for example if you want to create a generic app and launch it in GitHub or such for other people to use.
As for when to use class based view over function view i think this will depend on your use case, my advice is that you have to understand the advantage of each way, and IMHO it's pretty normal to have both implementation in a single project.
There was this nice article of Nick Coghlan on response to another great article CBV were a mistake that it worth to check.
Hope this was helpful :)
Im looking into XSS with various frameworks and CMS and whether they provide methods in protecting against it (not just programmaticly avoiding the situation).
I know that in Djangos templating language you can specify a variable as |safe I want to be able to allow actually safe html tags so the user can format text (simple things like etc), but strip such things as , onload attributes etc.
I would like to know whether Django recommends a method in doing this, not just using Python. I hope this makes sense
Jason
One of the core concepts of Django is that it's Python, and any Python lib should be usable with Django. They won't recreate the wheel unless there is good reason to. I believe HTML scrubbing/sanitizing is one of the things they've decided not to recreate.
BeautifulSoup is the python library you want to look into for any scrubbing/sanitizing though.
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)
I am building a library that will be used in several Python applications. It get multilingual e-mail templates from an RMDBS, and then variable replacement will be performed on the template in Python before the e-mail is sent.
In addition to variable replacement, I need the template library to support if, elif, and for statements in the templates.
I use Mako for most my projects, and also looked at Tempita as it doesn't provide a lot of features I don't need.
The concern I have is untrusted code execution - can someone point me at a template solution for Python that either does not support code execution, or will allow me to disable it?
From the Django book:
For that reason, it’s impossible to call Python code directly within Django templates. All “programming” is fundamentally limited to the scope of what template tags can do. It is possible to write custom template tags that do arbitrary things, but the out-of-the-box Django template tags intentionally do not allow for arbitrary Python code execution.
Give Django templates a try. It's a little tricky to set up outside of a Django app -- something to do with DJANGO_SETTINGS_MODULE, search around -- but may be trusted.
Have you checked out Jinja2? It's pretty much what you're talking about, and it's a great mix of powerful while keeping things simple and not giving the designer too much power. :)
If you've used Django's template system, it's very similar (if not based off of?) Jinja.