README

   1 This file documents the contents of this module
   2
   3 See the devel/ subdir for more devel-oriented doc.
   4
   5 ==================== 1 minute howto
   6
   7 * requirement is to have python + django installed django
   8 ** should be straightforward
   9 ** see devel/django-install.txt in case of trouble
  10
  11 * git clone git://git.onelab.eu/myslice-django.git
  12 -- or --
  13 * git clone ssh://yourlogin@git.onelab.eu/git/myslice-django.git
  14
  15 * edit myslice/settings.py and
  16 ** change DEVELOPER_ROOT if you didnt clone into ~/git/myslice-django
  17 ** change the location of your backend API (not yet supported)
  18
  19 * init django
  20 $ manage.py syncdb
  21
  22 [ at this point point it *might* be needed to run
  23 $ make allst
  24  but as far as running a local server is concerned you should be good without that
  25  feedbakc on this is appreciated]
  26
  27 * run a local server:
  28 $ manage.py runserver 0.0.0.0:8000
  29
  30 * use it from your browser
  31
  32
  33 ==================== Status
  34
  35 For now there's not much in here;
  36
  37 * Logging in should be easy using one of the few hard coded accounts
  38   this was the simplest possible way to demonstrate deferring authorization elsewhere
  39 * To logout, click on 'logged as *jean*', this shows a confirmation page..
  40
  41 Right now the UI has 4 views:
  42
  43 * the most useful one being the 'Plugin' view which demonstrates all the available plugins
  44   see test_plugin_view in engine/views.py
  45
  46 * slice view : only demonstrates how to use URLs to pass arguments along
  47 * scroll view : forget about that one, but it does illustrate that some pages can be made public (no need to login)
  48 * tab view : a hand-made tab widget
  49
  50 (last three from slice/views.py)
  51
  52 ==================== Contents: 1st level subdirs
  53
  54 ========== code from git
  55 * myslice:
  56   this is the django 'project', where to look for
  57   . settings.py
  58   . urls.py
  59
  60 * engine:
  61   the code for building / rendering plugins
  62
  63 * plugins:
  64   the actual code for plugins
  65
  66 * auth:
  67   a django 'app' that deals with authentication; see especially
  68   auth.backend.MyCustomBackend
  69   for how to use a separate authentication system,
  70   as well as settings.py for how to enable it
  71
  72 * slice:
  73   a django app for dealing with slice views
  74
  75 * insert_above:
  76   a third-party django app for adding on-the-fly mentions to css or js files that need to go in the header
  77
  78 * templates/
  79 * static/
  80   some global stuff:
  81    * templates (django templates, i.e. (essentially html) fragments that can be specializied)
  82    * static files (css, js, images..)
  83   see more about that below
  84
  85 * devel:
  86   no code in there, only various notes and other scripts useful for developers
  87
  88 ========== automatically generated
  89
  90 * all-static: (generated, no need to source-control)
  91   this is where 'manage.py collectstatic' will gather all your static contents if you run a local server
  92   make has convenience targets to refresh this area
  93   $ make clean-static
  94   $ make static
  95
  96 * myslice.sqlite3
  97   this is where django stores its own stuff, as per settings.py
  98
  99
 100 ==================== conventions for templates and static
 101
 102 * templates:
 103   we store this under templates/ within the corresponding app, e.g.
 104   auth/templates/login.html
 105   for now this is mostly about html, but the engine can be used for rendering anything including js(on) or whatever..
 106
 107 * static files:
 108   we chose to have all static files (images, but also javascript and stylesheets) in the various
 109   proj or app where they belong, under a static/ subdir that has this structure:
 110   where-it-belongs/
 111     static/
 112       img/
 113       css/
 114       js/
 115
 116
 117 NOTE. in essence any of these files can be moved around (from e.g. one templates/ dir to another)
 118 at any time without any change needed in the code
 119