Merge branch 'master' into async-github-repo-syncing

Author: gregmuellegger

.gitignore

@@ -6,6 +6,7 @@
 .coverage
 .idea
 .vagrant
+.tox
 _build
 cnames
 bower_components/

.travis.yml

@@ -1,13 +1,16 @@
 language: python
 python:
- - "2.7"
+ - 2.7
+sudo: false
+env:
+ - TOX_ENV=py27
+ - TOX_ENV=docs
+ #- TOX_ENV=lint
 install:
- - pip install flake8 stripe
- - pip install -r requirements.txt
+ - pip install tox
  - pip install coveralls
 script:
- #- flake8 `find . -iname "*.py" -not -ipath "*migration*"`
- - ./runtests.sh
+ - tox -e $TOX_ENV
 after_success:
  - coveralls
 notifications:

bower.json

@@ -14,7 +14,7 @@
     "tests"
   ],
   "dependencies": {
-    "jquery": "*",
+    "jquery": "~2.0.3",
     "underscore": "~1.7.0",
     "readthedocs-client": "https://github.com/agjohnson/readthedocs-client-js.git",
     "knockout": "~3.3.0",

docs/changelog.md

@@ -0,0 +1,60 @@
+# Changelog
+
+This document will track major changes in the project.
+
+Also note, this document is a Markdown file. This is mainly to keep parity with GitHub, and also because we can.
+
+## July 23, 2015
+
+
+* Django 1.8 Support Merged
+
+### Code Notes
+
+
+- Updated Django from `1.6.11` to `1.8.3`.
+- Removed South and ported the South migrations to Django's migration framework.
+- Updated django-celery from `3.0.23` to `3.1.26` as django-celery 3.0.x does not support Django 1.8.
+- Updated Celery from `3.0.24` to `3.1.18` because we had to update django-celery. We need to test this extensively and might need to think about using the new Celery API directly and dropping django-celery. See release notes: http://docs.celeryproject.org/en/latest/whatsnew-3.1.html
+- Updated tastypie from `0.11.1` to current master (commit `1e1aff3dd4dcd21669e9c68bd7681253b286b856`) as 0.11.x is not compatible with Django 1.8. No suprises expected but we should ask for a proper release, see release notes: https://github.com/django-tastypie/django-tastypie/blob/master/docs/release_notes/v0.12.0.rst
+- Updated django-oauth from `0.16.1` to `0.21.0`. No suprises expected, see release notes [in the docs](https://django-allauth.readthedocs.org/en/latest/changelog.html) and [finer grained in the repo](https://github.com/pennersr/django-allauth/blob/9123223f167959e4e5c4074408db068f725559d1/ChangeLog#L1-169)
+- Updated django-guardian from `1.2.0` to `1.3.0` to gain Django 1.8 support. No suprises expected, see release notes: https://github.com/lukaszb/django-guardian/blob/devel/CHANGES
+- Using `django-formtools` instead of removed `django.contrib.formtools` now. Based on the Django release notes, these modules are the same except of the package name.
+- Updated pytest-django from `2.6.2` to `2.8.0`. No tests required, but running the testsuite :smile: 
+- Updated psycopg2 from 2.4 to 2.4.6 as 2.4.5 is required by Django 1.8. No trouble expected as Django is the layer between us and psycopg2. Also it's only a minor version upgrade. Release notes: http://initd.org/psycopg/docs/news.html#what-s-new-in-psycopg-2-4-6
+- Added `django.setup()` to `conf.py` to load django properly for doc builds.
+- Added migrations for all apps with models in the `readthedocs/` directory
+
+### Deployment Notes
+
+After you have updated the code and installed the new dependencies, you need to run these commands on the server:
+
+```bash
+python manage.py migrate contenttypes
+python manage.py migrate projects 0002 --fake
+python manage.py migrate --fake-initial
+```
+
+Locally I had trouble in a test environment that pip did not update to the specified commit of tastypie. It might be required to use `pip install -U -r requirements/deploy.txt` during deployment.
+
+
+### Development Update Notes
+
+The readthedocs developers need to execute these commands when switching to this branch (or when this got merged into master):
+
+- **Before updating** please make sure that all migrations are applied:
+
+```bash
+python manage.py syncdb
+python manage.py migrate
+```
+
+- Update the codebase: `git pull`
+- You need to update the requirements with `pip install -r requirements.txt`
+- Now you need to fake the initial migrations:
+
+```bash
+python manage.py migrate contenttypes
+python manage.py migrate projects 0002 --fake
+python manage.py migrate --fake-initial
+```

docs/conf.py

@@ -3,10 +3,15 @@
 import os
 import sys
 
+from recommonmark.parser import CommonMarkParser
+
 sys.path.insert(0, os.path.abspath('../readthedocs'))
 os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings.sqlite")
 from django.conf import settings
 
+import django
+django.setup()
+
 
 sys.path.append(os.path.abspath('_ext'))
 extensions = [
@@ -16,7 +21,12 @@
     'djangodocs',
 ]
 templates_path = ['_templates']
-source_suffix = '.rst'
+
+source_suffix = ['.rst', '.md']
+source_parsers = {
+    '.md': CommonMarkParser,
+}
+
 master_doc = 'index'
 project = u'Read The Docs'
 copyright = u'2010, Eric Holscher, Charlie Leifer, Bobby Grace'

docs/custom_installs/local_rtd_vm.rst

@@ -8,7 +8,7 @@ Assumptions and Prerequisites
 * All python dependencies and setup tools are installed ::
 
   $ sudo apt-get install python-setuptools
-  $ sudo apt-get install built-essential
+  $ sudo apt-get install build-essential
   $ sudo apt-get install python-dev
   $ sudo apt-get install libevent-dev
   $ sudo easy_install pip 
@@ -37,7 +37,7 @@ To host your documentation on a local RTD installation, set it up in your VM. ::
     $ cd checkouts
     $ git clone https://github.com/rtfd/readthedocs.org.git
     $ cd readthedocs.org
-    $ sudo pip install -r pip_requirements.txt
+    $ sudo pip install -r requirements.txt
     
 Possible Error and Resolution
 `````````````````````````````
@@ -56,18 +56,14 @@ Possible Error and Resolution
 1. Run the following commands. ::
 
     $ cd readthedocs
-    $ ./manage.py syncdb
+    $ ./manage.py migrate
 
 2. This will prompt you to create a superuser account for Django. Enter appropriate details. For example: ::
 
     Username: monami.b
     Email address: [email protected]
     Password: pa$$word
 
-3. Run the migrate command. ::
-
-    $ ./manage.py migrate
-
 3. RTD Server Administration.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -76,9 +72,9 @@ Navigate to the ``../checkouts/readthedocs.org/readthedocs`` folder in your VM a
     $ ./manage.py runserver [VM IP ADDRESS]:8000
     $ curl -i http://[VM IP ADDRESS]:8000
 
-You should now be able to log into the admin interface from any PC in your LAN at http://[VM IP ADDRESS]:8000/admin using the superuser account created in django.
+You should now be able to log into the admin interface from any PC in your LAN at ``http://[VM IP ADDRESS]:8000/admin`` using the superuser account created in django.
 
-Go to the dashboard at  http://[VM IP ADDRESS]:8000/dashboard and follow these steps:
+Go to the dashboard at  ``http://[VM IP ADDRESS]:8000/dashboard`` and follow these steps:
 
 1. Point the repository to your corporate Git project where the documentation source is checked in. Example:
 git.corp.company.com:/git/docs/documentation.git
@@ -124,7 +120,7 @@ This provides all permissions for that particular remote session, which are revo
 4. Build Documentation on Local RTD Instance.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Log into http://[VM IP ADDRESS]:[PORT] using the django superuser creds and follow these steps.	
+Log into ``http://[VM IP ADDRESS]:[PORT]`` using the django superuser creds and follow these steps.	
 
 For a new project
 `````````````````

docs/development.rst

@@ -0,0 +1,160 @@
+=====================
+Development Standards
+=====================
+
+Front End Development
+=====================
+
+Background
+----------
+
+.. info::
+
+    Consider this the canonical resource for contributing Javascript and CSS. We
+    are currently in the process of modernizing our front end development
+    procedures. You will see a lot of different styles around the code base for
+    front end JavaScript and CSS.
+
+Our modern front end development stack includes the following tools:
+
+* `Gulp`_
+* `Bower`_
+* `Browserify`_
+* `Debowerify`_
+* And soon, `LESS`_
+
+We use the following libraries:
+
+* `Knockout`_
+* `jQuery`_
+* Several jQuery plugins
+
+Previously, JavaScript development has been done in monolithic files or inside
+templates. jQuery was added as a global object via an include in the base
+template to an external source. There are no standards currently to JavaScript
+libraries, this aims to solve that.
+
+The requirements for modernizing our front end code are:
+
+* Code should be modular and testable. One-off chunks of JavaScript in templates
+  or in large monolithic files are not easily testable. We currently have no
+  JavaScript tests.
+* Reduce code duplication.
+* Easy JavaScript dependency management.
+
+Modularizing code with `Browserify`_ is a good first step. In this development
+workflow, major dependencies commonly used across JavaScript includes are
+installed with `Bower`_ for testing, and vendorized as standalone libraries via
+`Gulp`_ and `Browserify`_. This way, we can easily test our JavaScript libraries
+against jQuery/etc, and have the flexibility of modularizing our code. See
+`JavaScript Bundles`_ for more information on what and how we are bundling.
+
+To ease deployment and contributions, bundled JavaScript is checked into the
+repository for now. This ensures new contributors don't need an additional front
+end stack just for making changes to our Python code base. In the future, this
+may change, so that assets are compiled before deployment, however as our front
+end assets are in a state of flux, it's easier to keep absolute sources checked
+in.
+
+Getting Started
+---------------
+
+You will need a working version of Node and NPM to get started. We won't cover
+that here, as it varies from platform to platform.
+
+To install these tools and dependencies::
+
+    npm install
+
+This will install locally to the project, not globally. You can install globally
+if you wish, otherwise make sure ``node_modules/.bin`` is in your PATH.
+
+Next, install front end dependencies::
+
+    bower install
+
+The sources for our bundles are found in the per-application path
+``static-src``, which has the same directory structure as ``static``. Files in
+``static-src`` are compiled to ``static`` for static file collection in Django.
+Don't edit files in ``static`` directly, unless you are sure there isn't a
+source file that will compile over your changes.
+
+To test changes while developing, which will watch source files for changes and
+compile as necessary, you can run `Gulp`_ with our development target::
+
+    gulp dev
+
+Once you are satisfied with your changes, finalize the bundles (this will
+minify library sources)::
+
+    gulp build
+
+If you updated any of our vendor libraries, compile those::
+
+    gulp vendor
+
+Make sure to check in both files under ``static`` and ``static-src``.
+
+Making Changes
+--------------
+
+If you are creating a new library, or a new library entry point, make sure to
+define the application source file in ``gulpfile.js``, this is not handled
+automatically right now.
+
+If you are bringing in a new vendor library, make sure to define the bundles you
+are going to create in ``gulpfile.js`` as well.
+
+Tests should be included per-application, in a path called ``tests``, under the
+``static-src/js`` path you are working in. Currently, we still need a test
+runner that accumulates these files.
+
+Deployment
+----------
+
+If merging several branches with JavaScript changes, it's important to do a
+final post-merge bundle. Follow the steps above to rebundle the libraries, and
+check in any changed libraries.
+
+JavaScript Bundles
+------------------
+
+There are several components to our bundling scheme:
+
+    Vendor library
+        We repackage these using `Browserify`_, `Bower`_, and `Debowerify`_ to
+        make these libraries available by a ``require`` statement.  Vendor
+        libraries are packaged separately from our JavaScript libraries, because
+        we use the vendor libraries in multiple locations. Libraries bundled
+        this way with `Browserify`_ are available to our libraries via
+        ``require`` and will back down to finding the object on the global
+        ``window`` scope.
+
+        Vendor libraries should only include libraries we are commonly reusing.
+        This currently includes `jQuery` and `Knockout`. These modules will be
+        excluded from libraries by special includes in our ``gulpfile.js``.
+
+    Minor third party libraries
+        These libraries are maybe used in one or two locations. They are
+        installed via `Bower`_ and included in the output library file. Because
+        we aren't reusing them commonly, they don't require a separate bundle or
+        separate include. Examples here would include jQuery plugins used on one
+        off forms, such as jQuery Payments.
+
+    Our libraries
+        These libraries are bundled up excluding vendor libraries ignored by
+        rules in our ``gulpfile.js``. These files should be organized by
+        function and can be split up into multiple files per application.
+
+        Entry points to libraries must be defined in ``gulpfile.js`` for now. We
+        don't have a defined directory structure that would make it easy to
+        imply the entry point to an application library.
+
+.. _`Bower`: http://bower.io
+.. _`Gulp`: http://gulpjs.com
+.. _`Browserify`: http://browserify.org
+.. _`Debowerify`: https://github.com/eugeneware/debowerify
+.. _`LESS`: http://lesscss.org
+
+.. _`jQuery`: http://jquery.com
+.. _`Knockout`: http://knockoutjs.com

docs/index.rst

@@ -73,9 +73,11 @@ Information about development is also available:
    :caption: Developer Documentation
 
    install
+   changelog
    contribute
    tests
    architecture
+   development
    symlinks
    settings
    i18n

docs/install.rst

@@ -73,13 +73,11 @@ This may take a while, so go grab a beverage. When it's done, build your
 database::
 
     cd readthedocs
-    ./manage.py syncdb
-
-This will prompt you to create a superuser account for Django. Do that. Then::
-
     ./manage.py migrate
 
-Go ahead and load in a couple users and a test projects::
+This will prompt you to create a superuser account for Django. Do that.
+
+Then go ahead and load in a couple users and a test projects::
 
     ./manage.py loaddata test_data