Merge branch 'master' of https://github.com/sh4nks/flaskbb

docs/conf.py

@@ -110,7 +110,7 @@ html_theme = 'flask'
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = ['_themes']
 html_theme_options = {
-    'index_logo': False,
+    'index_logo': "../_static/logo-full.png",
 }
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -268,3 +268,5 @@ texinfo_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
+
+autodoc_member_order = 'bysource'

docs/contents.rst.inc

@@ -5,5 +5,10 @@ Contents
    :maxdepth: 2
 
    installation
-   models
    plugins
+   plugin_tutorial/index
+   events
+   theming
+   settings
+   permissions
+   models

docs/events.rst

@@ -1,6 +1,76 @@
-Following events are available:
+.. _events:
+
+Events
+======
+
+In order to extend FlaskBB you will need to connect your callbacks with
+events.
+
+.. admonition:: Additional events
+
+    If you miss an event, feel free to open a new issue or create a pull
+    request.
+
+    A event can be created by placing a :func:`~flask.ext.plugins.emit_event`
+    function at specific places in the code which then can modify the behavior
+    of FlaskBB. The same thing applies for template events.
+
+    Python Event:
+
+    .. sourcecode:: python
+
+        def foobar(data)
+            somedata = "foobar"
+            emit_event("your-newly-contributed-event", somedata)
+
+
+    Template Event:
+
+    .. sourcecode:: html+jinja
+
+        {{ emit_event("your-newly-contributed-template-event") }}
+
+
+Available Events
+----------------
+
+
+Python Events
+~~~~~~~~~~~~~
+
+None at the moment. :(
+
+
+Template Events
+~~~~~~~~~~~~~~~
+
+.. data:: before-first-navigation-element
+
+    This event inserts a navigation link **before** the **first** navigation
+    element is rendered.
+
+    Example:
+
+    .. sourcecode:: python
+
+        def inject_navigation_element():
+            return render_template("navigation_element_snippet.html")
+
+        connect_event("before-first-navigation-element", inject_navigation_element)
+
+
+.. data:: after-last-navigation-element
+
+    This event inserts a navigation link **after** the **last** navigation
+    element is rendered.
+
+    Example:
+
+    .. sourcecode:: python
+
+        def inject_navigation_element():
+            return render_template("navigation_element_snippet.html")
+
+        connect_event("after-last-navigation-element", inject_navigation_element)
 
-    before-first-navigation-element
-    after-first-navigation-element
 
-event missing? open an issue or send a pull request.

docs/forummodels.rst

@@ -1,32 +0,0 @@
-Forum Models
-------------
-
-.. module:: flaskbb.forum.models
-
-.. autoclass:: Category
-   :members:
-   :inherited-members:
-
-.. autoclass:: Forum
-   :members:
-   :inherited-members:
-
-.. autoclass:: Topic
-   :members:
-   :inherited-members:
-
-.. autoclass:: Post
-   :members:
-   :inherited-members:
-
-.. autoclass:: TopicsRead
-   :members:
-   :inherited-members:
-
-.. autoclass:: ForumsRead
-   :members:
-   :inherited-members:
-
-.. autoclass:: Report
-   :members:
-   :inherited-members:

docs/index.rst

@@ -1,7 +1,7 @@
 :orphan:
 
-Welcome to FlaskBB's documentation!
-===================================
+Welcome to FlaskBB
+==================
 
 FlaskBB is a lightweight forum software in Flask.
 

docs/installation.rst

@@ -8,7 +8,7 @@ Installation
 
 
 Basic Setup
-===========
+-----------
 
 Virtualenv Setup
 ~~~~~~~~~~~~~~~~
@@ -39,11 +39,11 @@ and you should be switched automatically to your newly created virtualenv.
 To deactivate it you just have to type ``deactivate`` and if you want to work
 on it again, you need to type ``workon flaskbb``.
 
+
 Required Dependencies
 ~~~~~~~~~~~~~~~~~~~~~
 
 Now you can install the required dependencies.
-
 ::
 
      $ pip install -r requirements.txt
@@ -57,9 +57,7 @@ If you want to use it, be sure that a redis-server is running. If you decide
 to use redis, the `online guests` and `online users` are being tracked by redis,
 else it will only track the `online users` via a simple SQL query.
 
-On Archlinux
-------------
-
+**On Archlinux**
 ::
 
     # Install redis
@@ -74,9 +72,7 @@ On Archlinux
     # Optional: Start redis everytime you boot your machine
     $ sudo systemctl enable redis
 
-On Debian 7.0 (Wheezy)
-----------------------
-
+**On Debian 7.0 (Wheezy)**
 ::
 
     # Install redis
@@ -94,10 +90,11 @@ On Debian 7.0 (Wheezy)
 
 
 Configuration
-=============
+-------------
 
 Before you can start, you need to configure `FlaskBB`.
 
+
 Development
 ~~~~~~~~~~~
 
@@ -129,9 +126,7 @@ Mail Examples
 
 Both methods are included in the example configs.
 
-Google Mail
------------
-
+**Google Mail**
 ::
 
     MAIL_SERVER = "smtp.gmail.com"
@@ -141,9 +136,7 @@ Google Mail
     MAIL_PASSWORD = "your_password"
     MAIL_DEFAULT_SENDER = ("Your Name", "your_username@gmail.com")
 
-Local SMTP Server
------------------
-
+**Local SMTP Server**
 ::
 
     MAIL_SERVER = "localhost"
@@ -155,7 +148,7 @@ Local SMTP Server
 
 
 Installation
-============
+------------
 
 
 Development
@@ -184,13 +177,13 @@ and which password you want to use for your admin user
 
 
 Upgrading
-=========
+---------
 
 `A upgrade guide will be written when first stable version is released.`
 
 
 Deploying
-=========
+---------
 
 I prefer to use supervisor, uWSGI and nginx to deploy my apps, but if you have
 figured out how to deploy it in another way, please let me know, so I

docs/models.rst

@@ -3,10 +3,77 @@
 Available Models
 ================
 
-Here you can see a all available models.
+FlaskBB uses SQLAlchemy as it's ORM. The models are split in three modules
+which are covered below.
 
-.. toctree::
-   :maxdepth: 1
 
-   forummodels
-   usermodels
+Forum Models
+------------
+
+.. module:: flaskbb.forum.models
+
+This module contains all related models for the forums.
+
+The hierarchy looks like this: Category > Forum > Topic > Post. In the Report
+model are stored the reports and the TopicsRead and ForumsRead models are
+used to store the status if the user has read a specific forum or not.
+
+
+.. autoclass:: Category
+   :members:
+
+
+.. autoclass:: Forum
+   :members:
+
+
+.. autoclass:: Topic
+   :members:
+
+
+.. autoclass:: Post
+   :members:
+
+
+.. autoclass:: TopicsRead
+   :members:
+
+
+.. autoclass:: ForumsRead
+   :members:
+
+
+.. autoclass:: Report
+   :members:
+
+
+
+User Models
+-----------
+
+.. module:: flaskbb.user.models
+
+The user modules contains all related models for the users.
+
+.. autoclass:: User
+   :members:
+
+.. autoclass:: Group
+   :members:
+
+.. autoclass:: PrivateMessage
+   :members:
+
+
+Management Models
+-----------------
+
+.. module:: flaskbb.management.models
+
+The management module contains all related models for the management of FlaskBB.
+
+.. autoclass:: SettingsGroup
+   :members:
+
+.. autoclass:: Setting
+   :members:

docs/permissions.rst

@@ -1,3 +1,8 @@
+.. _permissions:
+
+Permission (WIP)
+================
+
 a moderator is allowed to do the following things:
 
     enter the management panel

docs/plugin_tutorial/index.rst

@@ -0,0 +1,17 @@
+.. _tutorial:
+
+Plugin Tutorial (WIP)
+=====================
+
+
+This tutorial is based on the plugin which is shipped by default with FlaskBB.
+If you want the full sourcecode in advance or for comparison, check out
+the `portal plugin`_.
+
+.. _portal plugin:
+   https://github.com/sh4nks/flaskbb/tree/master/flaskbb/plugins/portal
+
+.. toctree::
+   :maxdepth: 2
+
+   structure

docs/plugin_tutorial/structure.rst

@@ -0,0 +1,4 @@
+.. _structure:
+
+Step 1: Structure
+=================

docs/plugins.rst

@@ -1,15 +1,179 @@
 .. _plugins:
 
-Plugin API
-==========
+Plugins
+=======
 
 .. module:: flaskbb.plugins
 
-This part of the documenation explains how to create and use plugins.
+FlaskBB provides an easy way to extend the functionality of your forum
+via so called `Plugins`. Plugins do not modify the `core` of FlaskBB, so
+you can easily activate and deactivate them anytime. This part of the
+documentation only covers the basic things for creating plugins. If you are
+looking for a tutorial you need to go to this section of the documentation:
+:doc:`plugin_tutorial/index`.
+
+
+Structure
+---------
+
+A plugin has it's own folder where all the plugin specific files are living.
+For example, the structure of a plugin could look like this
+
+.. sourcecode:: text
+
+    my_plugin
+    |-- info.json                Contains the Plugin's metadata
+    |-- license.txt              The full license text of your plugin
+    |-- __init__.py              The plugin's main class is located here
+    |-- views.py
+    |-- models.py
+    |-- forms.py
+    |-- static
+    |   |-- style.css
+    |-- templates
+        |-- myplugin.html
+
+
+Management
+----------
+
+Deactivating
+~~~~~~~~~~~~
+
+The only way to disable a plugin without removing it is, to add a ``DISABLED``
+file in the plugin's root folder. You need to reload your application in order
+to have the plugin fully disabled. A disabled plugin could look like this::
+
+    my_plugin
+    |-- DISABLED    # Just add a empty file named "DISABLED" to disable a plugin
+    |-- info.json
+    |-- __init__.py
+
+.. important:: Restart the server.
+
+    You must restart the wsgi/in-built server in order to make the changes
+    effect your forum.
+
+
+Activating
+~~~~~~~~~~
+
+Simply remove the ``DISABLED`` file in the plugin directory and restart the
+server.
+
+
+Example Plugin
+--------------
+
+A really simple Plugin could look like this:
+
+.. sourcecode:: python
+
+    from flask import flash
+    from flask.ext.plugins import connect_event
+
+    from flaskbb.plugins import FlaskBBPlugin
+
+
+    # This is the name of your Plugin class which implements FlaskBBPlugin.
+    # The exact name is needed in order to be recognized as a plugin.
+    __plugin__ "HelloWorldPlugin"
+
+
+    def flash_index():
+        """Flashes a message when visiting the index page."""
+
+        flash("This is just a demonstration plugin", "success")
+
+
+    class HelloWorldPlugin(FlaskBBPlugin):
+        def setup(self):
+            connect_event(before-forum-index-rendered, flash_index)
+
+        def install(self):
+            # there is nothing to install
+            pass
+
+        def uninstall(self):
+            # and nothing to uninstall
+            pass
+
+
+Your plugins also needs a ``info.json`` file, where it stores some meta data
+about the plugin. For more information see the `Metadata <#metadata>`_
+section below.
+
+
+Metadata
+~~~~~~~~
+
+In order to get a working plugin, following metadata should be defined
+in a ``info.json`` file.
+
+``identifier`` : **required**
+    The plugin's identifier. It should be a Python identifier (starts with a
+    letter or underscore, the rest can be letters, underscores, or numbers)
+    and should match the name of the plugin's folder.
+
+``name`` : **required**
+    A human-readable name for the plugin.
+
+``author`` : **required**
+    The name of the plugin's author, that is, you. It does not have to include
+    an e-mail address, and should be displayed verbatim.
+
+``description``
+    A description of the plugin in a few sentences. If you can write multiple
+    languages, you can include additional fields in the form
+    ``description_lc``, where ``lc`` is a two-letter language code like ``es``
+    or ``de``. They should contain the description, but in the indicated
+    language.
+
+``website``
+    The URL of the plugin's Web site. This can be a Web site specifically for
+    this plugin, Web site for a collection of plugins that includes this plugin,
+    or just the author's Web site.
+
+``license``
+    A simple phrase indicating your plugin's license, like ``GPL``,
+    ``MIT/X11``, ``Public Domain``, or ``Creative Commons BY-SA 3.0``. You
+    can put the full license's text in the ``license.txt`` file.
+
+``version``
+    This is simply to make it easier to distinguish between what version
+    of your plugin people are using. It's up to the theme/layout to decide
+    whether or not to show this, though.
+
+
+Events
+------
+
+A full list with events can be found here :doc:`events`.
+
 
 Plugin Class
 ------------
 
 .. autoclass:: FlaskBBPlugin
-   :members:
-   :inherited-members:
+
+  .. autoattribute:: settings_key
+
+  .. autoattribute:: installable
+
+  .. autoattribute:: uninstallable
+
+  .. automethod:: setup
+
+  .. automethod:: install
+
+  .. automethod:: uninstall
+
+  .. automethod:: register_blueprint
+
+  .. automethod:: create_table
+
+  .. automethod:: drop_table
+
+  .. automethod:: create_all_tables
+
+  .. automethod:: drop_all_tables

docs/settings.rst

@@ -1,3 +1,8 @@
+.. _settings:
+
+Settings (WIP)
+==============
+
 extra fields:
     min
     max

docs/theming.rst

@@ -0,0 +1,4 @@
+.. _theming:
+
+Theming (WIP)
+=============

docs/usermodels.rst

@@ -1,17 +0,0 @@
-User Models
------------
-
-.. module:: flaskbb.user.models
-
-.. autoclass:: User
-   :members:
-   :inherited-members:
-
-.. autoclass:: Group
-   :members:
-   :inherited-members:
-
-.. autoclass:: PrivateMessage
-   :members:
-   :inherited-members:
-

flaskbb/forum/models.py

@@ -316,7 +316,7 @@ class Topic(db.Model):
 
     @property
     def url(self):
-        """Returns the url for the topic"""
+        """Returns the slugified url for the topic"""
         return url_for("forum.view_topic", topic_id=self.id, slug=self.slug)
 
     # Methods
@@ -611,7 +611,7 @@ class Forum(db.Model):
 
     @property
     def url(self):
-        """Returns the url for the forum"""
+        """Returns the slugified url for the forum"""
         return url_for("forum.view_forum", forum_id=self.id, slug=self.slug)
 
     # Methods
@@ -824,7 +824,7 @@ class Category(db.Model):
 
     @property
     def url(self):
-        """Returns the url for the category"""
+        """Returns the slugified url for the category"""
         return url_for("forum.view_category", category_id=self.id,
                        slug=self.slug)
 

flaskbb/plugins/__init__.py

@@ -30,7 +30,10 @@ class FlaskBBPlugin(Plugin):
 
         # Some helpers
     def register_blueprint(self, blueprint, **kwargs):
-        """Registers a blueprint."""
+        """Registers a blueprint.
+
+        :param blueprint: The blueprint which should be registered.
+        """
         current_app.register_blueprint(blueprint, **kwargs)
 
     def create_table(self, model, db):