Skip to content
This repository
Browse code

Removed playdoh docs from docs/ and made it a template for the forked…

… projects. Playdoh docs now live under gh.com/mozilla/playdoh-docs

Closes issue 31.
  • Loading branch information...
commit c6a1c1b78bd78b076da95a393ed535c2bc799981 1 parent c6d7e2a
Fred Wenzel fwenzel authored
79 docs/bestpractices.rst
Source Rendered
... ... @@ -1,79 +0,0 @@
1   -.. _bestpractices:
2   -
3   -==============
4   -Best Practices
5   -==============
6   -
7   -This page lists several best practices for writing secure web applications
8   -with playdoh.
9   -
10   -
11   -``|safe`` considered harmful
12   -----------------------------
13   -
14   -Using something like ``mystring|safe`` in a template will prevent Jinja2 from
15   -auto-escaping it. Sadly, this requires us to be really sure that ``mystring``
16   -is not raw, user-entered data. Otherwise we introduce an XSS vulnerability.
17   -
18   -We have therefore eliminated the need for ``|safe`` for localized strings. This
19   -works::
20   -
21   - {{ _('Hello <strong>world</strong>!') }}
22   -
23   -
24   -String interpolation
25   -~~~~~~~~~~~~~~~~~~~~
26   -
27   -When you *interpolate* data into such a string, however, the resulting output
28   -will lose its "safeness" and be escaped again. To mark the *localized part*
29   -of an interpolated string as safe, do not use ``|f(...)|safe``. The data could
30   -be unsafe. Instead, use the helper ``|fe(...)``. It will escape all its
31   -arguments before doing string interpolation, then return HTML that's safe to
32   -use::
33   -
34   - {{ _('Welcome back, <strong>{username}</strong>!')|fe(username=user.display_name) }}
35   -
36   -``|f(...)|safe`` is to be considered unsafe and **should not pass code
37   -review**.
38   -
39   -If you interpolate into a base string that does *not contain HTML*, you may
40   -keep on using ``|f(...)`` without ``|safe``, of course, as the auto-escaping
41   -won't harm anything::
42   -
43   - {{ _('Author name: {author}')|f(author=user.display_name) }}
44   -
45   -
46   -Form fields
47   -~~~~~~~~~~~
48   -
49   -Jinja2, unlike Django templates, by default does not consider Django forms
50   -"safe" to display. Thus, you'd use something like ``{{ form.myfield|safe }}``.
51   -
52   -In order to minimize the use of ``|safe`` (and thus possible unsafe uses of
53   -it), playdoh monkey-patches the Django forms framework so that form fields'
54   -HTML representations are considered safe by Jinja2 as well. Therefore, the
55   -following works as expected::
56   -
57   - {{ form.myfield }}
58   -
59   -
60   -Mmmmh, Cookies
61   ---------------
62   -
63   -Django's default way of setting a cookie is set_cookie_ on the HTTP response.
64   -Unfortunately, both **secure** cookies (i.e., HTTPS-only) and **httponly**
65   -(i.e., cookies not readable by JavaScript, if the browser supports it) are
66   -disabled by default.
67   -
68   -To be secure by default, we use commonware's ``cookies`` app. It makes secure
69   -and httponly cookies the default, unless specifically requested otherwise.
70   -
71   -To disable either of these patches, set ``COOKIES_SECURE = False`` or
72   -``COOKIES_HTTPONLY = False`` in ``settings.py``.
73   -
74   -You can exempt any cookie by passing ``secure=False`` or ``httponly=False`` to
75   -the ``set_cookie`` call, respectively::
76   -
77   - response.set_cookie('hello', value='world', secure=False, httponly=False)
78   -
79   -.. _set_cookie: http://docs.djangoproject.com/en/dev/ref/request-response/#django.http.HttpResponse.set_cookie
3  docs/build-github.zsh
... ... @@ -1,5 +1,8 @@
1 1 #!/bin/zsh
2 2
  3 +# A useful build script for projects hosted on github:
  4 +# It can build your Sphinx docs and push them straight to your gh-pages branch.
  5 +
3 6 # Should be run from the docs directory: (cd docs && ./build-github.zsh)
4 7
5 8 REPO=$(git config remote.origin.url)
8 docs/conf.py
@@ -40,8 +40,8 @@
40 40 master_doc = 'index'
41 41
42 42 # General information about the project.
43   -project = u'playdoh'
44   -copyright = u'2011, Mozilla'
  43 +project = u'a playdoh-based project'
  44 +copyright = u'2011, the authors'
45 45
46 46 # The version info for the project you're documenting, acts as replacement for
47 47 # |version| and |release|, also used in various other places throughout the
@@ -211,8 +211,8 @@
211 211 # One entry per manual page. List of tuples
212 212 # (source start file, name, description, authors, manual section).
213 213 man_pages = [
214   - ('index', 'playdoh', u'playdoh Documentation',
215   - [u'Mozilla'], 1)
  214 + ('index', 'a-playdoh-app', u"a-playdoh-app's Documentation",
  215 + [u'the authors'], 1)
216 216 ]
217 217
218 218
81 docs/docs.rst
Source Rendered
... ... @@ -1,81 +0,0 @@
1   -.. _docs:
2   -
3   -=========================
4   -Documentation with Sphinx
5   -=========================
6   -
7   -*(Borrowed from Zamboni)*
8   -
9   -For a reStructuredText Primer, see http://sphinx.pocoo.org/rest.html.
10   -
11   -
12   -Sections
13   ---------
14   -
15   -Sphinx doesn't care what punctuation you use for marking headings, but each new
16   -kind that it sees means one level lower in the outline. So, ::
17   -
18   - =========
19   - Heading 1
20   - =========
21   -
22   - Heading 2
23   - ---------
24   -
25   -will correspond to ::
26   -
27   - <h1>Heading 1</h1>
28   - <h2>Heading 2</h2>
29   -
30   -For consistency, this is what I'm using for headings in Zamboni::
31   -
32   - =========
33   - Heading 1
34   - =========
35   -
36   - Heading 2
37   - ---------
38   -
39   - Heading 3
40   - ~~~~~~~~~
41   -
42   - Heading 4
43   - *********
44   -
45   - Heading 5
46   - +++++++++
47   -
48   - Heading 6
49   - ^^^^^^^^^
50   -
51   -Use two newlines prior to a new heading. I'm only using one here for space
52   -efficiency.
53   -
54   -
55   -Sphinx Extras
56   --------------
57   -
58   -Use ``:src:`path/to/file.py``` to link to source files online. Example:
59   -:src:`settings.py`.
60   -
61   -
62   -Vim
63   ----
64   -
65   -Here's a nice macro for creating headings::
66   -
67   - let @h = "yypVr"
68   -
69   -
70   -Compiling Documentation
71   ------------------------
72   -
73   -Playdoh hosts its documentation on `github pages
74   -<http://mozilla.github.com/playdoh/>`_. When you change the docs, make sure
75   -they still build properly and look all right locally::
76   -
77   - cd docs && make html && open _build/html/index.html
78   -
79   -If they do, run a build and push it to gh-pages::
80   -
81   - ./build-github.zsh
46 docs/gettingstarted.rst
Source Rendered
... ... @@ -1,46 +0,0 @@
1   -Getting started
2   -===============
3   -
4   -Requirements
5   -------------
6   -
7   -You need Python 2.6.
8   -
9   -To check out playdoh, run::
10   -
11   - git clone --recursive git://github.com/mozilla/playdoh.git
12   -
13   -This project is set up to use a vendor library, i.e. a subdirectory ``vendor``
14   -that contains all pure Python libraries required by this project. The recursive
15   -checkout will also clone these requirements.
16   -
17   -In addition, there are compiled libraries (such as Jinja2) that you will need
18   -to build yourself, either by installing them from ``pypi`` or by using your
19   -favorite package manager for your OS.
20   -
21   -For development, you can run this in a `virtualenv environment`_::
22   -
23   - easy_install pip
24   - pip install -r requirements/compiled.txt
25   -
26   -For more information on vendor libraries, read :ref:`packages`.
27   -
28   -.. _virtualenv environment: http://pypi.python.org/pypi/virtualenv
29   -
30   -
31   -Starting a project based on playdoh
32   ------------------------------------
33   -The default branch of playdoh is ``base``. To start a new project, you fork
34   -playdoh and start working on your app in ``master`` (branched from base). If
35   -you start adding pieces that should go back into playdoh, you can apply the
36   -patch to base and move it upstream.
37   -
38   -Eventually you'll probably diverge enough that you'll want to delete the base
39   -branch.
40   -
41   -Publishing your repo
42   ---------------------
43   -
44   - git remote rename origin playdoh
45   - git remote add origin git@github.com:mozilla/foobar.git
46   - git push -u origin base
46 docs/index.rst
Source Rendered
... ... @@ -1,34 +1,19 @@
1   -===================================
2   -Welcome to playdoh's documentation!
3   -===================================
  1 +========================================
  2 +Welcome to this project's documentation!
  3 +========================================
4 4
5   -**Mozilla's Playdoh** is a web application template based on Django_.
  5 +This is a documentation template for a **web application based on Playdoh**.
  6 +Feel free to change this to your liking.
6 7
7   -Patches are welcome! Feel free to fork and contribute to this project on
8   -Github_.
9 8
10   -.. _Django: http://www.djangoproject.com/
11   -.. _Github: https://github.com/mozilla/playdoh
  9 +About playdoh
  10 +-------------
12 11
  12 +This project is based on **playdoh**. Mozilla's Playdoh is an open source
  13 +web application template based on `Django <http://www.djangoproject.com/>`_.
13 14
14   -Features
15   ---------
16   -Quick and dirty (and probably incomplete) feature list:
17   -
18   -* Rich, but "cherry-pickable" features out of the box:
19   -
20   - * Django
21   - * jinja2 template engine
22   - * Celery support
23   - * Simple database migrations
24   - * Full localization support
25   -
26   -* Secure by default:
27   -
28   - * SHA-512 default password hashing
29   - * X-Frame-Options: DENY by default
30   - * secure and httponly flags on cookies enabled by default
31   -
  15 +To learn more about it, step by the `playdoh project page
  16 +<https://github.com/mozilla/playdoh>`_.
32 17
33 18 Contents
34 19 --------
@@ -36,15 +21,6 @@ Contents
36 21 .. toctree::
37 22 :maxdepth: 1
38 23
39   - gettingstarted
40   - libs
41   - operations
42   - migrations
43   - l10n
44   - packages
45   - docs
46   - bestpractices
47   -
48 24
49 25 Indices and tables
50 26 ------------------
135 docs/l10n.rst
Source Rendered
... ... @@ -1,135 +0,0 @@
1   -Localization (L10n)
2   -===================
3   -
4   -So you'd like to localize your webapp. **Congratulations!**
5   -
6   -Playdoh comes with all of the libraries and tools you need in the dev and
7   -production requirements.
8   -
9   -Requirements
10   -------------
11   -
12   -The one set of low level tools not provided is gettext.
13   -
14   -::
15   -
16   - aptitude install gettext
17   - # or
18   - brew install gettext
19   -
20   -
21   -Environment Setup
22   ------------------
23   -
24   -Your top level directory named locale should be an SVN repository. This is
25   -because localizers are used to SVN and some tools like Pootle tie into it.
26   -Developers who never deal with L10n do not need to worry about this kind of
27   -setup. It's often easier to have a L10n dev setup, which a cron job updates
28   -the sources, updates the strings, and compiles the po files and lastly
29   -commiting to SVN.
30   -
31   -
32   -Initial Steps
33   --------------
34   -
35   -To allow localizers to translate your app on localize.mozilla.org, your .po
36   -files need to be in SVN. You want a checkout of your locale directory to live
37   -inside the git checkout under ``locale``.
38   -
39   -The following steps will get you started:
40   -
41   -#. Create an SVN repository with locale-based directories and ``templates``.
42   - You need at least::
43   -
44   - ./en_US
45   - ./en_US/LC_MESSAGES
46   - ./templates
47   - ./templates/LC_MESSAGES
48   -
49   -#. Check out this SVN repository inside your project path::
50   -
51   - cd /my/playdoh/project/dir/
52   - svn checkout https://svn.mozilla.org/projects/something/trunk/locale locale
53   -
54   - ## If you don't like svn, you may use git-svn too:
55   - # git svn clone https://svn.mozilla.org/projects/something/trunk/locale locale
56   -
57   -#. Now extract strings from your project::
58   -
59   - ./manage.py extract
60   - ./manage.py merge
61   -
62   -#. Commit it all.
63   -
64   -#. Build your .mo files and commit those as well::
65   -
66   - ./bin/compile-mo.sh locale/
67   - cd locale
68   - git add .
69   - git commit -m 'Built .mo files'
70   -
71   -
72   -Extracting Strings
73   -------------------
74   -
75   -If you've developed a feature and changed or added strings, you need to extract
76   -them and merge them into the existing .po files::
77   -
78   - ./manage.py extract
79   - ./manage.py merge
80   -
81   -Optionally compile all .mo files::
82   -
83   - ./bin/compile-mo.sh locale/
84   -
85   -
86   -Creating New Locales
87   ---------------------
88   -
89   -Assuming you want to add 'fr':
90   -
91   -#. ``mkdir -p locale/fr/LC_MESSAGES``
92   -#. ``./manage.py merge``
93   -
94   -or
95   -
96   -#. ``msginit --no-translator -l fr -i templates/LC_MESSAGES/messages.pot -o fr/LC_MESSAGES/messages.po``
97   -#. repeat for other POT files
98   -
99   -
100   -Advanced Steps
101   ---------------
102   -
103   -#. Some projects keep a copy of the SVN checkout in git. When doing that,
104   - keep in mind that ``git svn dcommit`` will change the commit message,
105   - thus changing the git commit ID. Therefore, always commit to SVN first,
106   - then push to git, never vice-versa::
107   -
108   - cd locale/
109   - # do something
110   - git commit -am 'did something'
111   - git svn dcommit && git push origin HEAD
112   -
113   -#. localize.mozilla.org does not automatically compile .mo files when a
114   - localizer commits to SVN. Neither does it automate the push over to
115   - git. There's a handy little script called ``autol10n`` that you can
116   - run as a cron job somewhere, which will:
117   -
118   - * pick up changed .po files from SVN,
119   - * compile the .mo files,
120   - * then (if necessary) push everything over to git...
121   - * ... and retag the git submodule to the latest revision.
122   -
123   - The script is available in playdoh under ``bin/autol10n.sh``.
124   -
125   -
126   -Q&A
127   ----
128   -
129   -* *Why SVN?* Our localizers like to use either SVN or Verbatim.
130   -* *Why a git repo to mirror an SVN repo?* This allows us to have an external
131   - reference ("git submodule") and deploy the app including its translations
132   - easily.
133   -* *How do I use gettext?* In templates we use jinja_
134   -
135   -.. _jinja: http://jinja.pocoo.org/docs/templates/#i18n
115 docs/libs.rst
Source Rendered
... ... @@ -1,115 +0,0 @@
1   -=========
2   -Libraries
3   -=========
4   -
5   -There are a number of libraries that either come bundled with playdoh or are
6   -otherwise useful for it.
7   -
8   -**Note:** Libraries marked with an \*asterisk\* are bundled with playdoh by default.
9   -
10   -
11   -Python
12   -======
13   -
14   -Database
15   ---------
16   -
17   -* `django-multidb-router <https://github.com/jbalogh/django-multidb-router>`_:
18   - Round-robin master/slave db router for Django 1.2.
19   -* `schematic <https://github.com/jbalogh/schematic>`_\*:
20   - Simple database migration tool.
21   -
22   -Deferred Execution (cron, message queues)
23   ------------------------------------------
24   -
25   -* `django-celery <https://github.com/ask/django-celery>`_\*:
26   - Celery integration for Django.
27   -* `django-cronjobs <https://github.com/jsocol/django-cronjobs>`_:
28   - A simple cron-running management command for Django.
29   -* `django-gearman <https://github.com/fwenzel/django-gearman>`_:
30   - A convenience wrapper for Gearman clients and workers in Django/Python.
31   -
32   -Deployment
33   -----------
34   -
35   -* `django-waffle <https://github.com/jsocol/django-waffle>`_:
36   - A feature flipper for Django.
37   -
38   -Internationalization (i18n) and Localization (L10n)
39   ----------------------------------------------------
40   -
41   -* `Babel <http://babel.edgewall.org/>`_\*:
42   - A collection of tools for internationalizing Python applications.
43   -* `pytz <http://pytz.sourceforge.net/>`_:
44   - World Timezone Definitions for Python.
45   -* `tower <https://github.com/clouserw/tower>`_\*:
46   - A library that builds on Babel and Jinja2 to make extracting strings easy and
47   - uniform.
48   -* `The Translate toolkit <http://translate.sourceforge.net/wiki/toolkit/index>`_\*:
49   - Tools for working between translation formats.
50   -
51   -Middleware
52   -----------
53   -
54   -* `commonware <http://github.com/jsocol/commonware>`_\*:
55   - Middlewares and other stuff we share.
56   -* `django-mobility <https://github.com/jbalogh/django-mobility>`_:
57   - Middleware and decorators for directing users to your mobile site.
58   -
59   -Mozilla
60   --------
61   -
62   -* `django-moz-header <https://github.com/mozilla/django-moz-header>`_:
63   - Common header/footer templates and CSS for Django-based Mozilla sites.
64   -* `django-mozilla-product-details <http://github.com/fwenzel/django-mozilla-product-details>`_:
65   - Pulls Mozilla product details library data from SVN and makes it available
66   - as Python dictionaries.
67   -
68   -Security and Data Sanitization
69   -------------------------------
70   -
71   -* `bleach <https://github.com/jsocol/bleach>`_:
72   - An easy, HTML5, whitelisting HTML sanitizer.
73   -* `django-sha2 <http://github.com/fwenzel/django-sha2>`_\*:
74   - Monkey-patches strong password hashing support into Django.
75   -* `happyforms <https://github.com/jbalogh/happyforms>`_:
76   - Extension to Django Forms that strips spaces.
77   -
78   -Templates and Caching
79   ----------------------
80   -
81   -* `django-cache-machine <https://github.com/jbalogh/django-cache-machine>`_:
82   - Automatic caching and invalidation for Django models through the ORM.
83   -* `jingo <https://github.com/jbalogh/jingo>`_\*:
84   - An adapter for using Jinja2 templates with Django.
85   -* `jingo-minify <https://github.com/jsocol/jingo-minify>`_\*:
86   - Concatenate and minify JS and CSS for Jinja2 + Jingo + Django.
87   -* `hera <https://github.com/clouserw/hera>`_:
88   - Client for Zeus Traffic Manager SOAP API.
89   -
90   -Testing
91   --------
92   -
93   -* `django-fixture-magic <https://github.com/davedash/django-fixture-magic>`_:
94   - Utilities to extract and manipulate Django fixtures.
95   -* `django-nose <https://github.com/jbalogh/django-nose>`_\*:
96   - Django test runner using *nose*.
97   -* `nose <http://somethingaboutorange.com/mrl/projects/nose/>`_\*:
98   - *nose* extends unittest to make testing easier.
99   -* `test-utils <https://github.com/jbalogh/test-utils>`_\*:
100   - A grab-bag of testing utilities that are pretty specific to our Django,
101   - Jinja2, and nose setup.
102   -
103   -Various
104   --------
105   -
106   -* `nuggets <https://github.com/mozilla/nuggets/>`_\*:
107   - Little utilities that don't deserve a package.
108   -
109   -
110   -JavaScript
111   -==========
112   -
113   -* `jQuery <http://jquery.com/>`_\*:
114   - The jQuery JavaScript library.
115   -
46 docs/migrations.rst
Source Rendered
... ... @@ -1,46 +0,0 @@
1   -.. _migrations:
2   -
3   -===================
4   -Database Migrations
5   -===================
6   -
7   -For database migrations, we use a strikingly simple tool called `schematic
8   -<https://github.com/jbalogh/schematic>`_.
9   -
10   -It runs numbered SQL files on top of your existing database. In a table
11   -named ``schema_version``, it remembers what migration number your database
12   -is currently on. If the table does not exist, it considers the database
13   -to be at migration 0 and creates the table.
14   -
15   -By default, migrations live in the ``migrations/`` directory. Run schematic
16   -like this::
17   -
18   - schematic migrations/
19   -
20   - # or, when using the vendor library:
21   - ./vendor/src/schematic/schematic migrations/
22   -
23   -
24   -Schematic vs. syncdb
25   ---------------------
26   -
27   -To create a DB from scratch, Django users run ``./manage.py syncdb``. It
28   -analyzes the models and generates SQL accordingly.
29   -
30   -Unfortunately, as the schema evolves, the output of *syncdb* will conflict
31   -with the *schematic* migrations you might have added to evolve older DBs.
32   -To circumvent this, consider the following:
33   -
34   -When done creating the first set of models, capture their syncdb-created SQL
35   -output as a baseline migration (number 1)::
36   -
37   - # edit some models in apps/foo/models.py
38   - ./manage.py sqlall foo > migrations/01-base.sql
39   -
40   -Then, as the schema evolves, add incremental migrations as ``02-...sql``, etc.
41   -
42   -When setting up a copy of the codebase from scratch in the future, forgo
43   -*syncdb* altogether and after setting your empty database's credentials
44   -correctly in ``settings_local.py``, just run ``schematic migrations/``. It will
45   -run your base migration, followed by incremental updates, and result in a
46   -database that's up to date with your latest existing databases.
100 docs/operations.rst
Source Rendered
... ... @@ -1,100 +0,0 @@
1   -Operations
2   -==========
3   -
4   -Care and feeding of a Playdoh-based app.
5   -
6   -Web Server
7   -----------
8   -
9   -Apps are typically run under Apache and mod_wsgi in production. Entry point::
10   -
11   - wsgi/playdoh.wsgi
12   -
13   -(or whatever you rename it to...)
14   -
15   -Developers can set that up or run in stand-alone mode::
16   -
17   - ./manage.py runserver 0.0.0.0:8000
18   -
19   -It is critical that developers run the app at least once via mod_wsgi before
20   -certifying an app as **stage ready**.
21   -
22   -Apache
23   -~~~~~~
24   -This is a typical virtualhost directive being used in production::
25   -
26   - <VirtualHost *:80>
27   - ServerName %HOSTNAME%
28   -
29   - Alias /media %APP_PATH/media
30   -
31   - WSGIScriptAlias / %APP_PATH/wsgi/playdoh.wsgi
32   - WSGIDaemonProcess playdoh processes=16 threads=1 display-name=playdoh
33   - WSGIProcessGroup playdoh
34   - </VirtualHost>
35   -
36   -
37   -gunicorn
38   -~~~~~~~~
39   -Totally optional and only for the cool kids.
40   -
41   -A lighter weight method of testing your mod_wsgi setup is by using
42   -`gunicorn <http://gunicorn.org/>`_.
43   -
44   -One time setup::
45   -
46   - pip install gunicorn
47   - ln -s wsgi/playdoh.wsgi wsgi/playdoh.py
48   -
49   -Each Time::
50   -
51   - touch wsgi/__init__.py
52   - gunicorn wsgi/playdoh:application
53   -
54   -
55   -Middleware Caching
56   -------------------
57   -
58   -TODO (memcache, redis)
59   -
60   -Frontend Caching
61   -----------------
62   -
63   -Apps are typically run behind a Zeus load balancer.
64   -
65   -Database
66   ---------
67   -
68   -Apps typically use a MySQL database.
69   -
70   -Message Queue
71   --------------
72   -
73   -Playdoh comes packaged with celery and works well with RabbitMQ.
74   -
75   -Updating your Environment
76   --------------------------
77   -
78   -You can run ``update_site.py`` to keep your app current.
79   -It does the following:
80   -
81   -* Updates source
82   -* Updates vendor libraries
83   -* Runs Database Migrations
84   -* Builds JS and CSS
85   -
86   -::
87   -
88   - ./bin/update_site.py -e dev
89   - ./bin/update_site.py -e stage
90   - ./bin/update_site.py -e prod
91   -
92   -You may pass a ``-v`` and update_site will explain what commands as it runs
93   -them.
94   -
95   -If there is an error on any step, the script stops.
96   -
97   -IT will typically put ``bin/update_site.py`` into a cron for auto-deployment
98   -to stage environments.
99   -
100   -Edit your copy to customize your branching and/or release practices.
192 docs/packages.rst
Source Rendered
... ... @@ -1,192 +0,0 @@
1   -.. _packages:
2   -
3   -==========================
4   -pip and friends: Packaging
5   -==========================
6   -
7   -*(largely borrowed from Zamboni)*
8   -
9   -Your app will depend on lots of tasty open source Python libararies. The list
10   -of all your dependencies should exist in two places:
11   -# requirements/prod.txt
12   -# As a submodule of vendor
13   -
14   -Ultimately your app code will run against the libraries under vendor via mod_wsgi.
15   -
16   -Why requirements? For developement, you can use virtualenvs and pip to have a
17   -tidy self-contained environment. If run from the Django runserver command, you
18   -don't even need a web server.
19   -
20   -
21   -The vendor library
22   -------------------
23   -
24   -The ``/vendor`` library is supposed to contain all packages and repositories.
25   -It enables the project to be deployed as one package onto many machines,
26   -without relying on PyPI-based installations on each target machine.
27   -
28   -By default, the vendor lib is checked out as a *git submodule* under
29   -``vendor/``. If you *do* need to check it out separately, do::
30   -
31   - git clone --recursive git://github.com/mozilla/playdoh-lib.git ./vendor
32   -
33   -Once the playdoh-lib repo has been downloaded to ``/vendor``, you only need to
34   -install the **compiled** packages (as defined in ``requirements/compiled.txt``).
35   -These can come from your system package manager or from::
36   -
37   - pip install -r requirements/compiled.txt
38   -
39   -
40   -Global vs. local library
41   -------------------------
42   -
43   -Playdoh provides its default library in the ``vendor/`` directory. You *may*
44   -fork and change it, but that will make it hard to pull updates from the
45   -upstream library later.
46   -
47   -If you want to make only a few **local additions** or override some of the
48   -libs in ``vendor/``, make those changes to the directory ``vendor-local/``
49   -instead, which (in ``manage.py``) is given precedence over playdoh's vendor
50   -dir.
51   -
52   -compiled.txt vs prod.txt
53   -------------------------
54   -If a Python library requires compilation, it should be recorded in compiled.txt.
55   -These aren't as portable and cannot be shipped in the vendor library.
56   -For local development, it's nice to pip install these into a virtualenv. A
57   -common practise is to use virtual env **only** for compiled libraries and
58   -vendor for the rest of your dependencies.
59   -
60   -Adding new packages
61   --------------------
62   -
63   -If we wanted to add a new dependency called ``cheeseballs`` to playdoh, you
64   -would add it to ``requirements/prod.txt``. If your library isn't used in
65   -production, then put it in ``requirements/dev.txt``. This makes it available
66   -to users installing into virtualenvs.
67   -
68   -We also need to add the new package to the vendor lib, since that is what runs
69   -in production...
70   -
71   -First, we need to add the source. There are two ways, depending on how
72   -this project is hosted:
73   -
74   -Non-git based repos (hg, CVS, tarball)
75   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76   -
77   -For such repos or for packages coming from PyPI, do::
78   -
79   - pip install -I --install-option="--home=`pwd`/vendor-local" cheeseballs
80   - cd vendor-local
81   - git add lib/python/cheeseballs
82   - git commit
83   -
84   -Optionally, if the package installs executables add them too. For
85   -example::
86   -
87   - cd vendor-local
88   - git add bin/cheeseballer
89   - git commit
90   -
91   -For hg repos that are not on PyPI, they can be installed with pip too
92   -but omit the ``--home`` option and use the ``--src`` instead. For
93   -example::
94   -
95   - pip install -I --src='vendor-local/src' \
96   - -e hg+http://bitbucket.org/jespern/django-piston@default#egg=django-piston
97   - cd vendor-local
98   - git add src/django-piston
99   - git commit
100   -
101   -Note: Installed source packages need to be appended to
102   -``vendor-local/vendor.pth``. See note below. For example::
103   -
104   - echo src/django-piston >> vendor-local/vendor.pth
105   -
106   -git-based repositories
107   -~~~~~~~~~~~~~~~~~~~~~~
108   -
109   -For a git-based package, add it as a git submodule::
110   -
111   - cd vendor-local
112   - git submodule add git://github.com/mozilla/cheeseballs.git src/cheeseballs
113   - git commit vendor.pth .gitmodules src/cheeseballs
114   -
115   -Further, you then need to update ``vendor-local/vendor.pth``. Python uses
116   -``.pth`` files to dynamically add directories to ``sys.path`` (`docs
117   -<http://docs.python.org/library/site.html>`_).
118   -
119   -The file format is simple. Consult ``vendor/vendor.pth`` for reference.
120   -
121   -Some packages (like ``html5lib`` and ``selenium``) are troublesome, because
122   -their source lives inside an extra subdirectory ``src/`` inside their checkout.
123   -So they need to be sourced with ``src/html5lib/src``, for example. Hopefully
124   -you won't hit any snags like that.
125   -
126   -Done. Try ``./manage.py shell`` and then ``import cheeseballs`` to make sure
127   -it worked.
128   -
129   -Testing Your Vendor Change
130   ----------------
131   -It's critical that you test your app running under mod_wsgi. Although you
132   -may use runserver day to day, go ahead and run some code through WSGI to
133   -prove vendor is setup properly. (throw an import into your view, etc)
134   -
135   -Advanced Topics
136   ----------------
137   -TODO [automate these instructions](<https://github.com/mozilla/playdoh/issues/30)
138   -
139   -Initial creation of the vendor library
140   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
141   -
142   -The vendor repo was seeded with ::
143   -
144   - pip install -I --install-option="--home=`pwd`/vendor" --src='vendor/src' -r requirements/dev.txt
145   -
146   - # ..delete some junk from vendor/lib/python...
147   -
148   - # Create the .pth file so Python can find our src libs.
149   - find src -type d -depth 1 >> vendor.pth
150   -
151   - # Add all the submodules.
152   - for f in src/*; do
153   - pushd $f >/dev/null && REPO=$(git config remote.origin.url) && popd > /dev/null && git submodule add $REPO $f
154   - done
155   - git add .
156   -
157   -
158   -Adding lots of git submodules
159   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
160   -
161   -As noted in *Adding new packages*, git-based packages are *git submodules*
162   -inside the vendor library. To set up the first batch of submodules, something
163   -like the following happened::
164   -
165   - for f in src/*
166   - pushd $f && REPO=$(git config remote.origin.url) && popd && git submodule add $REPO $f
167   -
168   -
169   -For reference: pip
170   -~~~~~~~~~~~~~~~~~~
171   -
172   -The classical method of installing is using pip. We have our packages
173   -separated into three files:
174   -
175   -:src:`requirements/compiled.txt`
176   - All packages that require (or go faster with) compilation. These can't be
177   - distributed cross-platform, so they need to be installed through your
178   - system's package manager or pip.
179   -
180   -:src:`requirements/prod.txt`
181   - The minimal set of packages you need to run zamboni in production. You
182   - also need to get ``requirements/compiled.txt``.
183   -
184   -:src:`requirements/dev.txt`
185   - All the packages needed for running tests and development servers. This
186   - automatically includes ``requirements/prod.txt``.
187   -
188   -
189   -With pip, you can get a development environment with::
190   -
191   - pip install -r requirements/dev.txt -r requirements/compiled.txt
192   -

0 comments on commit c6a1c1b

Please sign in to comment.
Something went wrong with that request. Please try again.