Restructure docs some

docs/contents.rst.inc

@@ -1,22 +1,30 @@
-Contents
---------
+User Documentation
+~~~~~~~~~~~~~~~~~~
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    installation
    cli
-   theming
-   plugins
-   plugin_development
-   hooks
-   settings
-   api
+   plugins/index
    faq
 
 
+Developer Documentation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   development/theming
+   development/hooks/index
+   development/plugin/index
+   development/api/index
+   development/settings
+
+
 Additional Information
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 .. toctree::
    :maxdepth: 2

docs/api.rst → docs/development/api/index.rst

@@ -3,6 +3,9 @@
 API
 ===
 
+This is the software API for FlaskBB, such as interfaces, models, exceptions
+and provided implementations where appropriate.
+
 .. toctree::
    :maxdepth: 2
 

docs/development/hooks/cli.rst

@@ -0,0 +1,13 @@
+.. _cli_hooks:
+
+.. currentmodule:: flaskbb.plugins.spec
+
+FlaskBB CLI Hooks
+=================
+
+These hooks are only invoked when using the ``flaskbb``
+CLI.
+
+.. autofunction:: flaskbb_cli
+.. autofunction:: flaskbb_shell_context
+

docs/development/hooks/event.rst

@@ -0,0 +1,19 @@
+.. _hooks_events:
+
+.. currentmodule:: flaskbb.plugins.spec
+
+FlaskBB Event Hooks
+===================
+
+.. autofunction:: flaskbb_event_post_save_before
+.. autofunction:: flaskbb_event_post_save_after
+.. autofunction:: flaskbb_event_topic_save_before
+.. autofunction:: flaskbb_event_topic_save_after
+.. autofunction:: flaskbb_event_user_registered
+.. autofunction:: flaskbb_authenticate
+.. autofunction:: flaskbb_post_authenticate
+.. autofunction:: flaskbb_authentication_failed
+.. autofunction:: flaskbb_reauth_attempt
+.. autofunction:: flaskbb_post_reauth
+.. autofunction:: flaskbb_reauth_failed
+

docs/development/hooks/forms.rst

@@ -0,0 +1,13 @@
+.. _hooks_form:
+
+.. currentmodule:: flaskbb.plugins.spec
+
+FlaskBB Form Hooks
+==================
+
+.. autofunction:: flaskbb_form_new_post_save
+.. autofunction:: flaskbb_form_new_post
+.. autofunction:: flaskbb_form_new_topic
+.. autofunction:: flaskbb_form_new_topic_save
+.. autofunction:: flaskbb_form_registration
+

docs/development/hooks/index.rst

@@ -0,0 +1,31 @@
+.. _hooks:
+
+Hooks
+=====
+
+In FlaskBB we distinguish from `Python Hooks <#python-hooks>`_ and
+`Template Hooks <#template-hooks>`_.
+Python Hooks are prefixed with ``flaskbb_`` and called are called in Python
+files whereas Template Hooks have to be prefixed with ``flaskbb_tpl_`` and are
+executed in the templates.
+
+If you miss a hook, feel free to open a new issue or create a pull
+request. The pull request should always contain a entry in this document
+with a small example.
+
+A hook needs a hook specification which are defined in
+:mod:`flaskbb.plugins.spec`. All hooks have to be prefixed with
+``flaskbb_`` and template hooks with ``flaskbb_tpl_``.
+
+Be sure to also check out the :ref:`api` documentation for interfaces that
+interact with these plugins in interesting ways.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   startup
+   cli
+   event
+   forms
+   template

docs/development/hooks/startup.rst

@@ -0,0 +1,28 @@
+.. _startup_hooks:
+
+.. currentmodule:: flaskbb.plugins.spec
+
+Application Startup Hooks
+=========================
+
+Application startup hooks are called when the application is created,
+either through a WSGI server (uWSGI or gunicorn for example) or by
+the ``flaskbb`` command.
+
+Unless noted, all FlaskBB hooks are called after the relevant builtin
+FlaskBB setup has run (e.g. ``flaskbb_load_blueprints`` is called after
+all standard FlaskBB blueprints have been loaded).
+
+The hooks below are listed in the order they are called.
+
+.. autofunction:: flaskbb_extensions
+.. autofunction:: flaskbb_load_blueprints
+.. autofunction:: flaskbb_jinja_directives
+.. autofunction:: flaskbb_request_processors
+.. autofunction:: flaskbb_errorhandlers
+.. autofunction:: flaskbb_load_migrations
+.. autofunction:: flaskbb_load_translations
+.. autofunction:: flaskbb_load_post_markdown_class
+.. autofunction:: flaskbb_load_nonpost_markdown_class
+.. autofunction:: flaskbb_additional_setup
+

docs/development/hooks/template.rst

@@ -0,0 +1,35 @@
+.. _hooks_template:
+
+.. currentmodule:: flaskbb.plugins.spec
+
+Template Hooks
+==============
+
+.. note::
+
+    Template hooks, which are used in forms, are usually rendered after the
+    hidden CSRF token field and before an submit field.
+
+
+.. autofunction:: flaskbb_tpl_navigation_before
+.. autofunction:: flaskbb_tpl_navigation_after
+.. autofunction:: flaskbb_tpl_user_nav_loggedin_before
+.. autofunction:: flaskbb_tpl_user_nav_loggedin_after
+.. autofunction:: flaskbb_tpl_form_registration_before
+.. autofunction:: flaskbb_tpl_form_registration_after
+.. autofunction:: flaskbb_tpl_form_user_details_before
+.. autofunction:: flaskbb_tpl_form_user_details_after
+.. autofunction:: flaskbb_tpl_form_new_post_before
+.. autofunction:: flaskbb_tpl_form_new_post_after
+.. autofunction:: flaskbb_tpl_form_new_topic_before
+.. autofunction:: flaskbb_tpl_form_new_topic_after
+.. autofunction:: flaskbb_tpl_profile_settings_menu
+.. autofunction:: flaskbb_tpl_profile_sidebar_stats
+.. autofunction:: flaskbb_tpl_post_author_info_before
+.. autofunction:: flaskbb_tpl_post_author_info_after
+.. autofunction:: flaskbb_tpl_post_content_before
+.. autofunction:: flaskbb_tpl_post_content_after
+.. autofunction:: flaskbb_tpl_post_menu_before
+.. autofunction:: flaskbb_tpl_post_menu_after
+.. autofunction:: flaskbb_tpl_topic_controls
+.. autofunction:: flaskbb_tpl_admin_settings_menu

docs/plugin_development.rst → docs/development/plugin/developing.rst

@@ -1,5 +1,4 @@
-.. _plugin_development:
-
+.. _plugin_developing:
 
 Developing new Plugins
 ======================
@@ -165,90 +164,5 @@ coerce the input value into the specified type.::
         'extra': {"choices": available_forums, "coerce": int}
     }
 
-For more information see the :doc:`settings` chapter.
-
-
-Using Hooks
------------
-Hooks are invoked based on an event occurring within FlaskBB. This makes it
-possible to change the behavior of certain actions without modifying the
-actual source code of FlaskBB.
-
-For your plugin to actually do something useful, you probably want to 'hook'
-your code into FlaskBB. This can be done throughout a lot of places in the
-code. FlaskBB loads and calls the hook calls hook functions from registered
-plugins for any given hook specification.
-
-Each hook specification has a corresponding hook implementation. By default,
-all hooks that are prefix with ``flaskbb_`` will be marked as a standard
-hook implementation. It is possible to modify the behavior of hooks.
-For example, default hooks are called in LIFO registered order.
-Although, registration order might not be deterministic. A hookimpl
-can influence its call-time invocation position using special attributes. If
-marked with a "tryfirst" or "trylast" option it will be executed first or last
-respectively in the hook call loop::
-
-    hookimpl = HookimplMarker('flaskbb')
-
-    @hookimpl(trylast=True)
-    def flaskbb_additional_setup(app):
-        return "save the best for last"
-
-
-In order to extend FlaskBB with your Plugin you will need to connect your
-callbacks to the hooks.
-
-Let's look at an actually piece of `used code`_.
-
-.. sourcecode:: python
-
-    def flaskbb_load_blueprints(app):
-        app.register_blueprint(portal, url_prefix="/portal")
-
-By defining a function called ``flaskbb_load_blueprints``, which has a
-corresponding hook specification under the same name. FlaskBB will pass
-in an ``app`` object as specified in the hook spec, which we will use to
-register a new blueprint. It is also possible to completely omit the ``app``
-argument from the function where it is **not possible** to add new arguments to
-the hook implemention.
-
-For a complete list of all available hooks in FlaskBB see the :doc:`hooks`
-section.
-
-pytest and pluggy are good resources to get better understanding on how to
-write `hook functions`_ using `pluggy`_.
-
-.. _`used code`: https://github.com/sh4nks/flaskbb-plugins/blob/master/portal/portal/__init__.py#L31
-.. _`hook functions`: https://docs.pytest.org/en/latest/writing_plugins.html#writing-hook-functions
-.. _`pluggy`: https://pluggy.readthedocs.io/en/latest/#defining-and-collecting-hooks
-
-
-Plugin Registry
----------------
-The plugin registry holds all available plugins. It shows the plugin's status
-whether it is enabled or disabled, installable or installed. The registry also
-holds a reference to the plugin's instance, provides an interface to access
-the plugins metadata and stores its settings.
-
-You can query it like any SQLAlchemy Model::
-
-    plugin = PluginRegistry.query.filter_by(name="portal").first()
-
-
-.. autoclass:: flaskbb.plugins.models.PluginRegistry
-    :members:
-
-
-Plugin Manager
---------------
-FlaskBB overrides the PluginManager from pluggy to provide some additional functionality like accessing the information stored in a setup.py file. The plugin manager will only list the currently enabled plugins and can be used to directly access the plugins instance by its name.
-
-
-Accessing a plugins instance is as easy as::
-
-    plugin_instance = current_app.pluggy.get_plugin(name)
-
+For more information see the :ref:`settings` chapter.
 
-.. autoclass:: flaskbb.plugins.manager.FlaskBBPluginManager
-    :members:
-    :inherited-members:

docs/development/plugin/hooks.rst

@@ -0,0 +1,57 @@
+.. _plugin_development_hooks:
+
+Using Hooks
+===========
+
+Hooks are invoked based on an event occurring within FlaskBB. This makes it
+possible to change the behavior of certain actions without modifying the
+actual source code of FlaskBB.
+
+For your plugin to actually do something useful, you probably want to 'hook'
+your code into FlaskBB. This can be done throughout a lot of places in the
+code. FlaskBB loads and calls the hook calls hook functions from registered
+plugins for any given hook specification.
+
+Each hook specification has a corresponding hook implementation. By default,
+all hooks that are prefix with ``flaskbb_`` will be marked as a standard
+hook implementation. It is possible to modify the behavior of hooks.
+For example, default hooks are called in LIFO registered order.
+Although, registration order might not be deterministic. A hookimpl
+can influence its call-time invocation position using special attributes. If
+marked with a "tryfirst" or "trylast" option it will be executed first or last
+respectively in the hook call loop::
+
+    hookimpl = HookimplMarker('flaskbb')
+
+    @hookimpl(trylast=True)
+    def flaskbb_additional_setup(app):
+        return "save the best for last"
+
+
+In order to extend FlaskBB with your Plugin you will need to connect your
+callbacks to the hooks.
+
+Let's look at an actually piece of `used code`_.
+
+.. sourcecode:: python
+
+    def flaskbb_load_blueprints(app):
+        app.register_blueprint(portal, url_prefix="/portal")
+
+By defining a function called ``flaskbb_load_blueprints``, which has a
+corresponding hook specification under the same name. FlaskBB will pass
+in an ``app`` object as specified in the hook spec, which we will use to
+register a new blueprint. It is also possible to completely omit the ``app``
+argument from the function where it is **not possible** to add new arguments to
+the hook implemention.
+
+For a complete list of all available hooks in FlaskBB see the
+:ref:`hooks` section.
+
+pytest and pluggy are good resources to get better understanding on how to
+write `hook functions`_ using `pluggy`_.
+
+.. _`used code`: https://github.com/sh4nks/flaskbb-plugins/blob/master/portal/portal/__init__.py#L31
+.. _`hook functions`: https://docs.pytest.org/en/latest/writing_plugins.html#writing-hook-functions
+.. _`pluggy`: https://pluggy.readthedocs.io/en/latest/#defining-and-collecting-hooks
+

docs/development/plugin/index.rst

@@ -0,0 +1,11 @@
+.. _plugin_development:
+
+Plugin Development
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   developing
+   hooks
+   manager

docs/development/plugin/manager.rst

@@ -0,0 +1,41 @@
+.. _plugin_management:
+
+
+Plugin Management
+=================
+
+FlaskBB provides a couple of helpers for helping with plugin management.
+
+
+Plugin Registry
+---------------
+The plugin registry holds all available plugins. It shows the plugin's status
+whether it is enabled or disabled, installable or installed. The registry also
+holds a reference to the plugin's instance, provides an interface to access
+the plugins metadata and stores its settings.
+
+You can query it like any SQLAlchemy Model::
+
+    plugin = PluginRegistry.query.filter_by(name="portal").first()
+
+
+.. autoclass:: flaskbb.plugins.models.PluginRegistry
+    :members:
+
+
+Plugin Manager
+--------------
+FlaskBB overrides the PluginManager from pluggy to provide some additional
+functionality like accessing the information stored in a setup.py file. The
+plugin manager will only list the currently enabled plugins and can be used to
+directly access the plugins instance by its name.
+
+
+Accessing a plugins instance is as easy as::
+
+    plugin_instance = current_app.pluggy.get_plugin(name)
+
+
+.. autoclass:: flaskbb.plugins.manager.FlaskBBPluginManager
+    :members:
+    :inherited-members:

docs/hooks.rst

@@ -1,120 +0,0 @@
-.. _hooks:
-
-Hooks
-=====
-
-In FlaskBB we distinguish from `Python Hooks <#python-hooks>`_ and
-`Template Hooks <#template-hooks>`_.
-Python Hooks are prefixed with ``flaskbb_`` and called are called in Python
-files whereas Template Hooks have to be prefixed with ``flaskbb_tpl_`` and are
-executed in the templates.
-
-If you miss a hook, feel free to open a new issue or create a pull
-request. The pull request should always contain a entry in this document
-with a small example.
-
-A hook needs a hook specification which are defined in
-:mod:`flaskbb.plugins.spec`. All hooks have to be prefixed with
-``flaskbb_`` and template hooks with ``flaskbb_tpl_``.
-
-Be sure to also check out the :ref:`api` documentation for interfaces that
-interact with these plugins in interesting ways.
-
-
-Python Hooks
-------------
-
-.. currentmodule:: flaskbb.plugins.spec
-
-Application Startup Hooks
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Application startup hooks are called when the application is created,
-either through a WSGI server (uWSGI or gunicorn for example) or by
-the ``flaskbb`` command.
-
-Unless noted, all FlaskBB hooks are called after the relevant builtin
-FlaskBB setup has run (e.g. ``flaskbb_load_blueprints`` is called after
-all standard FlaskBB blueprints have been loaded).
-
-The hooks below are listed in the order they are called.
-
-.. autofunction:: flaskbb_extensions
-.. autofunction:: flaskbb_load_blueprints
-.. autofunction:: flaskbb_jinja_directives
-.. autofunction:: flaskbb_request_processors
-.. autofunction:: flaskbb_errorhandlers
-.. autofunction:: flaskbb_load_migrations
-.. autofunction:: flaskbb_load_translations
-.. autofunction:: flaskbb_load_post_markdown_class
-.. autofunction:: flaskbb_load_nonpost_markdown_class
-.. autofunction:: flaskbb_additional_setup
-
-
-FlaskBB CLI Hooks
-~~~~~~~~~~~~~~~~~
-
-These hooks are only invoked when using the ``flaskbb``
-CLI.
-
-.. autofunction:: flaskbb_cli
-.. autofunction:: flaskbb_shell_context
-
-
-FlaskBB Event Hooks
-~~~~~~~~~~~~~~~~~~~
-
-.. autofunction:: flaskbb_event_post_save_before
-.. autofunction:: flaskbb_event_post_save_after
-.. autofunction:: flaskbb_event_topic_save_before
-.. autofunction:: flaskbb_event_topic_save_after
-.. autofunction:: flaskbb_event_user_registered
-.. autofunction:: flaskbb_authenticate
-.. autofunction:: flaskbb_post_authenticate
-.. autofunction:: flaskbb_authentication_failed
-.. autofunction:: flaskbb_reauth_attempt
-.. autofunction:: flaskbb_post_reauth
-.. autofunction:: flaskbb_reauth_failed
-
-
-FlaskBB Form Hooks
-~~~~~~~~~~~~~~~~~~
-
-.. autofunction:: flaskbb_form_new_post_save
-.. autofunction:: flaskbb_form_new_post
-.. autofunction:: flaskbb_form_new_topic
-.. autofunction:: flaskbb_form_new_topic_save
-.. autofunction:: flaskbb_form_registration
-
-
-Template Hooks
---------------
-
-.. note::
-
-    Template hooks, which are used in forms, are usually rendered after the
-    hidden CSRF token field and before an submit field.
-
-
-.. autofunction:: flaskbb_tpl_navigation_before
-.. autofunction:: flaskbb_tpl_navigation_after
-.. autofunction:: flaskbb_tpl_user_nav_loggedin_before
-.. autofunction:: flaskbb_tpl_user_nav_loggedin_after
-.. autofunction:: flaskbb_tpl_form_registration_before
-.. autofunction:: flaskbb_tpl_form_registration_after
-.. autofunction:: flaskbb_tpl_form_user_details_before
-.. autofunction:: flaskbb_tpl_form_user_details_after
-.. autofunction:: flaskbb_tpl_form_new_post_before
-.. autofunction:: flaskbb_tpl_form_new_post_after
-.. autofunction:: flaskbb_tpl_form_new_topic_before
-.. autofunction:: flaskbb_tpl_form_new_topic_after
-.. autofunction:: flaskbb_tpl_profile_settings_menu
-.. autofunction:: flaskbb_tpl_profile_sidebar_stats
-.. autofunction:: flaskbb_tpl_post_author_info_before
-.. autofunction:: flaskbb_tpl_post_author_info_after
-.. autofunction:: flaskbb_tpl_post_content_before
-.. autofunction:: flaskbb_tpl_post_content_after
-.. autofunction:: flaskbb_tpl_post_menu_before
-.. autofunction:: flaskbb_tpl_post_menu_after
-.. autofunction:: flaskbb_tpl_topic_controls
-.. autofunction:: flaskbb_tpl_admin_settings_menu

docs/permissions.rst

@@ -1,11 +0,0 @@
-.. _permissions:
-
-Permission (WIP)
-================
-
-a moderator is allowed to do the following things:
-
-    enter the management panel
-    process reports
-    edit user (if he has the permission)
-    ban users (if he has the permission)

docs/plugins.rst → docs/plugins/index.rst

@@ -12,7 +12,7 @@ for us. A list of available plugins can be found at the `GitHub Wiki`_. A
 proper index for FlaskBB Plugins and Themes still have to be built.
 
 If you are interested in creating new plugins, checkout out the
-:doc:`Developing new Plugins </plugin_development>` page.
+:ref:`Developing new Plugins <plugin_development>` page.
 
 .. _`pluggy plugin system`: https://pluggy.readthedocs.io/en/latest/
 .. _`GitHub Wiki`: https://github.com/sh4nks/flaskbb/wiki