diff --git a/docs/deleteview.html b/docs/deleteview.rst similarity index 100% rename from docs/deleteview.html rename to docs/deleteview.rst diff --git a/docs/index.rst b/docs/index.rst index aef0019..65f3c0b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,12 +6,14 @@ Introduction =========================================== -Smartmin was born out of the frustration of the Django admin site not being well suited to being exposed to clients. Smartmin aims to allow you to quickly build scaffolding which you can customize by using Django class based views. +Smartmin was born out of the frustration of the Django admin site not being well suited to being exposed to clients. +Smartmin aims to allow you to quickly build scaffolding which you can customize by using Django class based views. It is very opininated in how it works, if you don't agree, Smartmin may not be for you: - Permissions are used to gate access to each page, embrace permissions throughout and you'll love this -- CRUDL operations at the object level, that is, Create, Read, Update, Delete and List, permissions and views are based around this +- CRUDL operations at the object level, that is, Create, Read, Update, Delete and List, permissions and views are based + around this - URL automapping via the the CRUDL objects, this should keep things very very DRY The full documentation can be found at: @@ -27,7 +29,8 @@ Built in Rwanda by Nyaruka Ltd: Dependencies =========================================== -Smartmin depends on features in Django 1.7, so you'll need to be running at least that version. It also depends on the most excellent django-guardian package to deal with object level permissions, so you'll need to install that as well. +Smartmin depends on features in Django 1.7, so you'll need to be running at least that version. It also depends on the +most excellent django-guardian package to deal with object level permissions, so you'll need to install that as well. Installation =========================================== @@ -73,30 +76,39 @@ You'll also need to add smartmin and guardian to your installed apps:: 'smartmin', ) -Finally, if you want to use the default smartmin views for managing users and logging in, you'll want to add the smartmin.users app to your ``urls.py``:: +Finally, if you want to use the default smartmin views for managing users and logging in, you'll want to add the +smartmin.users app to your ``urls.py``:: - urlpatterns = patterns('', + urlpatterns = [ # .. other patterns .. url(r'^users/', include('smartmin.users.urls')), - ) + ] You can now sync your database and start the server:: - % python manage.py syncdb + % python manage.py migrate % python manage.py runserver -And if you want to see a Smartmin view in action, check out smartmin's user management pages for a demo that functionality by pointing your browser to:: +And if you want to see a Smartmin view in action, check out smartmin's user management pages for a demo that +functionality by pointing your browser to:: http://localhost:8000/users/user -From here you can create, update and list users on the system, all using standard smartmin views. The total code to create all this functionality is less than 30 lines of Python. +From here you can create, update and list users on the system, all using standard smartmin views. The total code to +create all this functionality is less than 30 lines of Python. Versioning: =========================================== -Smartmin will release major versions in step (or rather a bit behind) Django's major releases. Version 1.8 actually works against both Version 1.7 and Version 1.8 and we hope to support the past two versions in each release. Smartmin is used in quite a few of our projects, so we don't rock the boat too much, even in major releases. That said, we don't guarantee that major releases always be backwards compatible. +Smartmin will release major versions in step (or rather a bit behind) Django's major releases. Version 1.11 actually +works against Django 1.11, 1.10 and 1.9 - we hope to support the 3 most recent versions in each release. Smartmin +is used in quite a few of our projects, so we don't rock the boat too much, even in major releases. That said, we don't +guarantee that major releases always be backwards compatible. -At the onset of each new Django version we will upgrade Twitter Bootstrap to the current version. Currently for 1.8, which targets Django 1.8, that means Twitter Bootstrap 2. Note that some of our screenshots are a bit outdated, our standard views now use Bootstrap styling, not the more Django admin looking pages shown in our docs. (PRs accepted to fix this!) +At the onset of each new Django version we will upgrade Twitter Bootstrap to the current version. Currently for 1.11, +which targets Django 1.11, that means Twitter Bootstrap 3. Note that some of our screenshots are a bit outdated, our +standard views now use Bootstrap styling, not the more Django admin looking pages shown in our docs. (PRs accepted to +fix this!) Contents: =========================================== @@ -111,7 +123,6 @@ Contents: updateview deleteview listview - crudl templates perms users diff --git a/docs/misc.rst b/docs/misc.rst index c494347..4d4ff10 100644 --- a/docs/misc.rst +++ b/docs/misc.rst @@ -1,12 +1,34 @@ -Miscelaneous Utilities +Miscellaneous Utilities ======================== We've included a few bonus features that we find useful when developing django apps. +Collect SQL Command +------------------- + +This is a management command to extract SQL operations from your Django migrations and organize them into several master +SQL scripts:: + + python manage.py collect_sql + +This will extract any SQL statements passed to RunSQL operations and write them to ``current_indexes.sql``, +``current_triggers.sql`` and ``current_functions.sql``. + +Migrate Manual Command +---------------------- + +This is a management command to make it easier to run long-running Django data migrations manually. To make a migration +compatible with this command, include a function called ``apply_manual`` which takes no parameters:: + + python manage.py migrate_manual flows 0123 + +This will manually run the migration in the flows app with the prefix 0123. + Django Compressor -=================== +----------------- -Smartmin already comes with django-compressor support. The default ``base.html`` template will wrap your CSS and JS in ``{% compress %}`` tags in order to optimize your page load times. +Smartmin already comes with django-compressor support. The default ``base.html`` template will wrap your CSS and JS in +``{% compress %}`` tags in order to optimize your page load times. If you want to enable this, you'll just need to add ``compressor`` to your ``INSTALLED_APPS`` in ``settings.py``:: @@ -18,11 +40,13 @@ If you want to enable this, you'll just need to add ``compressor`` to your ``INS And change the commented out ``{# compress #}`` tags in ``base.html`` to be valid, ie: ``{% compress %}``. -pdb Template Tag -=================== +PDB Template Tag +---------------- -We all love ``pdb.set_trace()`` to help us debug problems, but sometimes you want to do the same thing in a template. The smartmin template tags include just that:: +We all love ``pdb.set_trace()`` to help us debug problems, but sometimes you want to do the same thing in a template. +The smartmin template tags include just that:: {% pdb %} -Will throw you into a pdb session when it hits that tag. You can examine variables in the session (including the request) and debug your template live. +Will throw you into a pdb session when it hits that tag. You can examine variables in the session (including the +request) and debug your template live. diff --git a/docs/readview.html b/docs/readview.rst similarity index 100% rename from docs/readview.html rename to docs/readview.rst