Permalink
Browse files

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...
fwenzel committed Jun 9, 2011
1 parent c6d7e2a commit c6a1c1b78bd78b076da95a393ed535c2bc799981
Showing with 18 additions and 833 deletions.
  1. +0 −79 docs/bestpractices.rst
  2. +3 −0 docs/build-github.zsh
  3. +4 −4 docs/conf.py
  4. +0 −81 docs/docs.rst
  5. +0 −46 docs/gettingstarted.rst
  6. +11 −35 docs/index.rst
  7. +0 −135 docs/l10n.rst
  8. +0 −115 docs/libs.rst
  9. +0 −46 docs/migrations.rst
  10. +0 −100 docs/operations.rst
  11. +0 −192 docs/packages.rst
View
@@ -1,79 +0,0 @@
-.. _bestpractices:
-
-==============
-Best Practices
-==============
-
-This page lists several best practices for writing secure web applications
-with playdoh.
-
-
-``|safe`` considered harmful
-----------------------------
-
-Using something like ``mystring|safe`` in a template will prevent Jinja2 from
-auto-escaping it. Sadly, this requires us to be really sure that ``mystring``
-is not raw, user-entered data. Otherwise we introduce an XSS vulnerability.
-
-We have therefore eliminated the need for ``|safe`` for localized strings. This
-works::
-
- {{ _('Hello <strong>world</strong>!') }}
-
-
-String interpolation
-~~~~~~~~~~~~~~~~~~~~
-
-When you *interpolate* data into such a string, however, the resulting output
-will lose its "safeness" and be escaped again. To mark the *localized part*
-of an interpolated string as safe, do not use ``|f(...)|safe``. The data could
-be unsafe. Instead, use the helper ``|fe(...)``. It will escape all its
-arguments before doing string interpolation, then return HTML that's safe to
-use::
-
- {{ _('Welcome back, <strong>{username}</strong>!')|fe(username=user.display_name) }}
-
-``|f(...)|safe`` is to be considered unsafe and **should not pass code
-review**.
-
-If you interpolate into a base string that does *not contain HTML*, you may
-keep on using ``|f(...)`` without ``|safe``, of course, as the auto-escaping
-won't harm anything::
-
- {{ _('Author name: {author}')|f(author=user.display_name) }}
-
-
-Form fields
-~~~~~~~~~~~
-
-Jinja2, unlike Django templates, by default does not consider Django forms
-"safe" to display. Thus, you'd use something like ``{{ form.myfield|safe }}``.
-
-In order to minimize the use of ``|safe`` (and thus possible unsafe uses of
-it), playdoh monkey-patches the Django forms framework so that form fields'
-HTML representations are considered safe by Jinja2 as well. Therefore, the
-following works as expected::
-
- {{ form.myfield }}
-
-
-Mmmmh, Cookies
---------------
-
-Django's default way of setting a cookie is set_cookie_ on the HTTP response.
-Unfortunately, both **secure** cookies (i.e., HTTPS-only) and **httponly**
-(i.e., cookies not readable by JavaScript, if the browser supports it) are
-disabled by default.
-
-To be secure by default, we use commonware's ``cookies`` app. It makes secure
-and httponly cookies the default, unless specifically requested otherwise.
-
-To disable either of these patches, set ``COOKIES_SECURE = False`` or
-``COOKIES_HTTPONLY = False`` in ``settings.py``.
-
-You can exempt any cookie by passing ``secure=False`` or ``httponly=False`` to
-the ``set_cookie`` call, respectively::
-
- response.set_cookie('hello', value='world', secure=False, httponly=False)
-
-.. _set_cookie: http://docs.djangoproject.com/en/dev/ref/request-response/#django.http.HttpResponse.set_cookie
View
@@ -1,5 +1,8 @@
#!/bin/zsh
+# A useful build script for projects hosted on github:
+# It can build your Sphinx docs and push them straight to your gh-pages branch.
+
# Should be run from the docs directory: (cd docs && ./build-github.zsh)
REPO=$(git config remote.origin.url)
View
@@ -40,8 +40,8 @@
master_doc = 'index'
# General information about the project.
-project = u'playdoh'
-copyright = u'2011, Mozilla'
+project = u'a playdoh-based project'
+copyright = u'2011, the authors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -211,8 +211,8 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'playdoh', u'playdoh Documentation',
- [u'Mozilla'], 1)
+ ('index', 'a-playdoh-app', u"a-playdoh-app's Documentation",
+ [u'the authors'], 1)
]
View
@@ -1,81 +0,0 @@
-.. _docs:
-
-=========================
-Documentation with Sphinx
-=========================
-
-*(Borrowed from Zamboni)*
-
-For a reStructuredText Primer, see http://sphinx.pocoo.org/rest.html.
-
-
-Sections
---------
-
-Sphinx doesn't care what punctuation you use for marking headings, but each new
-kind that it sees means one level lower in the outline. So, ::
-
- =========
- Heading 1
- =========
-
- Heading 2
- ---------
-
-will correspond to ::
-
- <h1>Heading 1</h1>
- <h2>Heading 2</h2>
-
-For consistency, this is what I'm using for headings in Zamboni::
-
- =========
- Heading 1
- =========
-
- Heading 2
- ---------
-
- Heading 3
- ~~~~~~~~~
-
- Heading 4
- *********
-
- Heading 5
- +++++++++
-
- Heading 6
- ^^^^^^^^^
-
-Use two newlines prior to a new heading. I'm only using one here for space
-efficiency.
-
-
-Sphinx Extras
--------------
-
-Use ``:src:`path/to/file.py``` to link to source files online. Example:
-:src:`settings.py`.
-
-
-Vim
----
-
-Here's a nice macro for creating headings::
-
- let @h = "yypVr"
-
-
-Compiling Documentation
------------------------
-
-Playdoh hosts its documentation on `github pages
-<http://mozilla.github.com/playdoh/>`_. When you change the docs, make sure
-they still build properly and look all right locally::
-
- cd docs && make html && open _build/html/index.html
-
-If they do, run a build and push it to gh-pages::
-
- ./build-github.zsh
View
@@ -1,46 +0,0 @@
-Getting started
-===============
-
-Requirements
-------------
-
-You need Python 2.6.
-
-To check out playdoh, run::
-
- git clone --recursive git://github.com/mozilla/playdoh.git
-
-This project is set up to use a vendor library, i.e. a subdirectory ``vendor``
-that contains all pure Python libraries required by this project. The recursive
-checkout will also clone these requirements.
-
-In addition, there are compiled libraries (such as Jinja2) that you will need
-to build yourself, either by installing them from ``pypi`` or by using your
-favorite package manager for your OS.
-
-For development, you can run this in a `virtualenv environment`_::
-
- easy_install pip
- pip install -r requirements/compiled.txt
-
-For more information on vendor libraries, read :ref:`packages`.
-
-.. _virtualenv environment: http://pypi.python.org/pypi/virtualenv
-
-
-Starting a project based on playdoh
------------------------------------
-The default branch of playdoh is ``base``. To start a new project, you fork
-playdoh and start working on your app in ``master`` (branched from base). If
-you start adding pieces that should go back into playdoh, you can apply the
-patch to base and move it upstream.
-
-Eventually you'll probably diverge enough that you'll want to delete the base
-branch.
-
-Publishing your repo
---------------------
-
- git remote rename origin playdoh
- git remote add origin git@github.com:mozilla/foobar.git
- git push -u origin base
View
@@ -1,50 +1,26 @@
-===================================
-Welcome to playdoh's documentation!
-===================================
+========================================
+Welcome to this project's documentation!
+========================================
-**Mozilla's Playdoh** is a web application template based on Django_.
+This is a documentation template for a **web application based on Playdoh**.
+Feel free to change this to your liking.
-Patches are welcome! Feel free to fork and contribute to this project on
-Github_.
-.. _Django: http://www.djangoproject.com/
-.. _Github: https://github.com/mozilla/playdoh
+About playdoh
+-------------
+This project is based on **playdoh**. Mozilla's Playdoh is an open source
+web application template based on `Django <http://www.djangoproject.com/>`_.
-Features
---------
-Quick and dirty (and probably incomplete) feature list:
-
-* Rich, but "cherry-pickable" features out of the box:
-
- * Django
- * jinja2 template engine
- * Celery support
- * Simple database migrations
- * Full localization support
-
-* Secure by default:
-
- * SHA-512 default password hashing
- * X-Frame-Options: DENY by default
- * secure and httponly flags on cookies enabled by default
-
+To learn more about it, step by the `playdoh project page
+<https://github.com/mozilla/playdoh>`_.
Contents
--------
.. toctree::
:maxdepth: 1
- gettingstarted
- libs
- operations
- migrations
- l10n
- packages
- docs
- bestpractices
-
Indices and tables
------------------
Oops, something went wrong.

0 comments on commit c6a1c1b

Please sign in to comment.