Various doc fixes.

.gitignore

@@ -1,5 +1,6 @@
 .idea
 .tox
+.travis-solo
 .DS_Store
 .coverage
 .vagrant

.travis.yml

@@ -6,6 +6,7 @@ python:
 before_install:
  - sudo apt-get update
  - sudo apt-get install -y poppler-utils
+ - sudo rmdir /dev/shm && sudo ln -Tsf /{run,dev}/shm
 
 # Install Python dependencies
 install:

Makefile

@@ -65,7 +65,7 @@ clean:
 	rm -f junit-py27.xml
 
 tidy: clean
-	rm -rf .tox
+	rm -rf .tox .travis-solo
 
 update-pot:
 	# _n => ngettext, _l => lazy_gettext

abilian/app.py

@@ -57,7 +57,7 @@ class PluginManager(object):
   def load_plugins(self):
     """Discovers and load plugins.
 
-    At this point, prefer explicit loading using the `register_plugin`
+    At this point, prefer explicit loading using the :method:~`register_plugin`
     method.
     """
     loader = AppLoader()
@@ -87,10 +87,10 @@ class Application(Flask, ServiceManager, PluginManager):
   """
   default_config = default_config
 
-  #: custom apps may want to always load some plugins: list them here
+  #: Custom apps may want to always load some plugins: list them here.
   APP_PLUGINS = ()
 
-  #: environment variable used to locate a config file to load last (after
+  #: Environment variable used to locate a config file to load last (after
   #: instance config file). Use this if you want to override some settings on a
   #: configured instance.
   CONFIG_ENVVAR = 'ABILIAN_CONFIG'

abilian/core/celery.py

@@ -7,14 +7,17 @@
 from celery.loaders.base import BaseLoader
 from celery.utils.imports import symbol_by_name
 
+
 def default_app_factory():
   from abilian.app import Application
   return Application()
 
+
 def is_celery_setting(key):
   return key.startswith('CELERY') \
     or key in ('BROKER_URL',)
 
+
 class FlaskLoader(BaseLoader):
   """
   """

abilian/testing/__init__.py

@@ -51,10 +51,10 @@ class BaseTestCase(TestCase):
   ensure harder test isolation.
   """
 
-  #: config class to use for :attr:`application_class` configuration
+  #: Config class to use for :attr:`.application_class` configuration.
   config_class = TestConfig
 
-  #: Application class to instantiate
+  #: Application class to instantiate.
   application_class = Application
 
   TEST_INSTANCE_PATH = None
@@ -100,10 +100,10 @@ def tearDownClass(cls):
     TestCase.tearDownClass()
 
   def get_setup_config(self):
-    """ Called by `create_app` Override this if you want to tweak the config
+    """ Called by :meth:`create_app` Override this if you want to tweak the config
     before :attr:`application_class` is instanciated.
 
-    :return: an instance of :attr:`config_class`, or anything that is valid
+    :return: an instance of :attr:`config_class`, or anything that is a valid
              config object for Flask.
     """
     return self.config_class()
@@ -155,7 +155,7 @@ def tearDown(self):
 
   @property
   def db(self):
-    """ Shortcut to application db object
+    """ Shortcut to the application db object.
     """
     return self.app.extensions['sqlalchemy'].db
 
@@ -174,7 +174,8 @@ def get(self, url, validate=True):
   # TODO: post(), put(), etc.
 
   def assert_valid(self, response):
-    """ Validate html with config.VALIDATOR_URL
+    """ Validate `response.data` as HTML using validator provided by
+    `config.VALIDATOR_URL`.
     """
     # FIXME: put this and document in TestConfig class
     validator_url = self.app.config.get('VALIDATOR_URL') \

abilian/web/action.py

@@ -7,13 +7,15 @@
 
 __all__ = ('Action', 'ModalActionMixin', 'actions')
 
+
 def getset(f):
-  """ shortcut for a custom getter/ standard setter
+  """ Shortcut for a custom getter/ standard setter
   """
   return property(f, f)
 
+
 class Action(object):
-  """ Action interface
+  """ Action interface.
   """
   category = None
   name = None
@@ -22,13 +24,13 @@ class Action(object):
   icon = None
   _url = None
 
-  #: a string for a simple endpoint, a tuple (endpoint_name, kwargs) to be
-  #: passed to `url_for(endpoint_name, **kwargs)` or a callable which accept a
+  #: A string for a simple endpoint, a tuple ``(endpoint_name, kwargs)`` to be
+  #: passed to ``url_for(endpoint_name, **kwargs)`` or a callable which accept a
   #: context dict and returns a valid value.
   endpoint = None
 
-  #: a bool (or something that can be converted to bool), or a callable which
-  #: accept a context dict as parameter.
+  #: A boolean (or something that can be converted to boolean), or a callable
+  #: which accepts a context dict as parameter.
   condition = None
 
   template_string = (
@@ -52,7 +54,7 @@ def __init__(self, category, name, title=None, description=None, icon=None,
 
     self._active = True
 
-  #: boolean. Inactive actions are unconditionnaly skipped
+  #: Boolean. Inactive actions are unconditionnaly skipped.
   @getset
   def active(self, value=None):
     active = self._active
@@ -61,7 +63,6 @@ def active(self, value=None):
       self._active = active = value
     return active
 
-
   def _get_and_call(self, attr):
     attr = '_' + attr
     value = getattr(self, attr)
@@ -115,18 +116,18 @@ def endpoint(self, endpoint):
     self._endpoint = endpoint
 
   def available(self, context):
-    """ Determine if this actions is available in this ``context``. ``context``
+    """ Determine if this actions is available in this `context`. `context`
     is a dict whose content is left to application needs; if :attr:`.condition`
-    is a callable it receives ``context`` in parameter.
+    is a callable it receives `context` in parameter.
     """
     if not self._active:
       return False
     return self.pre_condition(context) and self._check_condition(context)
 
   def pre_condition(self, context):
-    """ Called by :meth:``.available`` before checking condition. Subclasses may
+    """ Called by :meth:`.available` before checking condition. Subclasses may
     override it to ease creating actions with repetitive check (for example:
-    actions that apply on a given content type only)
+    actions that apply on a given content type only).
     """
     return True
 
@@ -174,7 +175,7 @@ class ActionRegistry(object):
 
   From your application use the instanciated registry :data:`.actions`.
 
-  The registry is available in jinja2 templates as ``actions``
+  The registry is available in jinja2 templates as `actions`.
   """
   __EXTENSION_NAME = 'abilian:actions'
 
@@ -191,18 +192,18 @@ def add_registry_to_jinja_context():
       return dict(actions=self)
 
   def installed(self, app=None):
-    """ Return True if the registry has been installed in current applications
+    """ Return `True` if the registry has been installed in current applications
     """
     if app == None:
       app = current_app
     return self.__EXTENSION_NAME in app.extensions
 
   def register(self, *actions):
-    """ Register ``actions`` in current application. All ``actions`` must be an
+    """ Register `actions` in the current application. All `actions` must be an
     instance of :class:`.Action` or one of its subclasses.
 
-    If ``overwrite`` is True then it is allowed to overwrite an existing
-    action with same name and category; else ValueError is raised.
+    If `overwrite` is `True`, then it is allowed to overwrite an existing
+    action with same name and category; else `ValueError` is raised.
     """
     assert self.installed(), "Actions not enabled on this application"
     assert all(map(lambda a: isinstance(a, Action), actions))
@@ -217,8 +218,8 @@ def actions(self, context=None):
 
     Actions are filtered according to :meth:`.Action.available`.
 
-    if ``context`` is None, then current action context is used
-    (:attr:``context``)
+    if `context` is None, then current action context is used
+    (:attr:`context`).
     """
     assert self.installed(), "Actions not enabled on this application"
     result = {}
@@ -234,8 +235,8 @@ def for_category(self, category, context=None):
 
     Actions are filtered according to :meth:`.Action.available`.
 
-    if ``context`` is None, then current action context is used
-    (:attr:``context``)
+    if `context` is None, then current action context is used
+    (:attr:`context`)
     """
     assert self.installed(), "Actions not enabled on this application"
     actions = self._state['categories'].get(category, [])

abilian/web/csrf.py

@@ -6,31 +6,31 @@
 
 def field():
   """
-  Return an instance of wtforms.ext.csrf.fields.CSRFTokenField, suitable for
-  rendering. Renders an empty string if config.CSRF_ENABLED is not set.
+  Return an instance of `wtforms.ext.csrf.fields.CSRFTokenField`, suitable for
+  rendering. Renders an empty string if `config.CSRF_ENABLED` is not set.
   """
   return Form().csrf_token
 
 
 def name():
   """ Field name expected to have CSRF token. Useful for passing it to
-  javascript for instance.
+  JavaScript for instance.
   """
   return u'csrf_token'
 
 
 def token():
-  """ Value of current csrf token. Useful for passing it to javascript for
+  """ Value of current csrf token. Useful for passing it to JavaScript for
   instance.
   """
   return field().current_token or u''
 
 
 def protect(view):
-  """ Protect a view agains CSRF attacks by checking 'csrf_token' value in
-  submitted values. Do nothing if config.CSRF_ENABLED is not set.
+  """ Protect a view agains CSRF attacks by checking `csrf_token` value in
+  submitted values. Do nothing if `config.CSRF_ENABLED` is not set.
 
-  Raises werkzeug.exceptions.Forbidden if validation fails.
+  Raises `werkzeug.exceptions.Forbidden` if validation fails.
   """
   @wraps(view)
   def csrf_check(*args, **kwargs):

abilian/web/views.py

@@ -12,6 +12,7 @@
 
 http_error_pages = Blueprint('http_error_pages', __name__)
 
+
 @http_error_pages.route('/<int:code>')
 def error_page(code):
   """ Helper for development to show 403, 404, 500..."""

docs/quickstart.rst

@@ -1,3 +1,4 @@
 Quick Start
 ===========
 
+This section needs to be written.