Commits

Miks Kalniņš committed 0835a8d

Initial documenation and few fixes for outdated information.

  • Participants
  • Parent commits 78da12d

Comments (0)

Files changed (4)

docs/devel/development.rst

 
   - flask-script for command line scripts
   - flask-babel / babel / pytz for i18n/l10n
-  - flask-themes for theme switching
   - flask-cache as cache storage abstraction
 * werkzeug for low level web/http page serving, debugging, builtin server, etc.
 * jinja2 for templating, such as the theme and user interface
 
 Templates and Themes
 --------------------
-Moin uses jinja2 as its templating engine and Flask-Themes as a flask extension to
-support multiple themes, each theme has static data like css and templates.
+Moin uses jinja2 as its templating engine and theme plugins support multiple themes,
+each theme has static data like css and templates.
 
 When rendering a template, the template is expanded within an environment of
 values it can use. In addition to this general environment, parameters can

docs/devel/plugins.rst

+.. warning::
+
+   Partly implemented and need more work.
+   
+===========
+Plugins
+===========
+
+*******************
+Plugin development
+*******************
+
+Creating custom plugins
+=======================
+The best way to create a plugin is by making a seperate Python package.
+
+.. tip:: You can use ExamplePlugin package located in :file:`contrib` directory as a starting point.
+
+Plugin system is besed on OO principes and uses `Python ABCs <http://docs.python.org/library/abc.html>`_ . All plugin types must implement their specific base
+class provided by MoinMoin package. All base classes are currently located in :keyword:`MoinMoin.plugin` module.
+
+
+Examples
+========
+
+As of now there aren't too many examples. There is an example plugin located in :file:`contrib/ExamplePlugin`.
+Also most of the plugin types have inbuilt plugins in :keyword:`MoinMoin` package itself and you can use them as reference.
+
+
+**************************
+Plugin system development
+**************************
+
+Notes
+========
+
+New code
+------------
+If possible new modules which are implemented as plugins shouldn't use wrappers as it's extra code and complexity which is not needed. Wrappers as they are used now is a simple way out of a lot of refactoring to make already written functionality into something that fits with the plugin system.
+
+Plugin loading/config chicken-egg problem
+-----------------------------------------------------
+For now I'm solving it by moving some of the function calls out of config. To be it seems very logical that config doesn't call mayor app functions when it's made (util functions are fine) and those are all called when config has been parsed/initialized.
+
+Blueprints
+-------------
+At the moment already defined themes have higher priority than those defined in Blueprint Plugin package. For example if blueprint tries to render "index.html" template and it has it in "BlueprintPlugin/templates/index.html" folder, it will still render the default "index.html" template found in MoinMoin template directory. I think I can "fix" it by changing theme code a bit (the render_template method which I already changed in themes plugin implementation). Another way is to simply prefix templates in Blueprint packages. Basically have to chose which have higher priority, as it is now, it makes sense considering how themes work.
+
+Metadata
+------------
+Currently we have no way to read it without initializing the plugin itself. This should be fixed somehow later on.
+
+Translations
+---------------
+Should be handled by plugin authors, Moin should expose helper functions and provide examples to make it easier for plugin authors.
+
+Plugin loading
+------------------
+So far it works more or less like this:
+
+ #. Admin provides list of enabled plugin packages.
+ #. System loads all of these packages.
+ #. System initializes all clasess which implement PluginBase, giving as parameter their config.
+
+You can quite easily add more layers of who enables what especially if you have layered configuation.
+
+TO-DO
+====
+ * Write the rest of the wrappers, not all inbuilt functionality have wrappers. Finish writting those so all already written code can be used in configuration.
+ * Finish the rest of the plugin types
+ * Slowly move away from wrappers around already supported classes and integrate plugin system more tightly with the core code. This requires quite a lot refactoring.
+ * If new plugin types are introduced or new code "modules" which could become type of a plugin, they shouldn't use wrappers, but instead have most of the code in the plugin base class.
+ * More configuraton, plugin examples are needed. Still a good reference is inbuilt plugins.
+ * i18n helper functions just to make it easier for plugin authors to implement i18n. (Some examples would also help) 
+ * Refactor startup code, right now the code seems very non-lineral and all over the place which means there are sometimes problems accessing things which are not initialized yet. There should be a clear pipeline of what starts after what and where.
+ * Need more core plugin system tests.
+ * Refactor theme code, it should be more straight forward.
+ * Introduce a plugin container so you don't have to rewrite all the meta information if it stays the same accross multiple plugin types in a plugin package.
+ * Add signals to the core code. Some good examples which need to be added:
+   - Stores are ready (plugins can write stuff to store)
+   - App has been created and can be accessed.
+ * Some day we could have nice web interface for site admins to enable/disable plugins.
+ * Maybe ACL helper functions for plugins, need more research.
+
+Plugin types and other functionality
+---------------------------------------------
+Done:
+
+ * Auth
+ * Themes
+ * Stores
+ * Blueprints
+ * Serialized items
+    - Not tested but should be doable with most plugins, need a way to initiate the process (Could be Blueprint or Commandline Script)
+
+On hold:
+
+ * Items
+    - Too volatile, more than one person working on them at the moment.
+
+Not done:
+
+ * Adding signals to moinmoin core code where it makes sense
+ * Commandline Scripts
+ * Other mimitype support plugins
+ * Converters/macros
+ * Other implementation of groups/dicts/etc. (low priority)
+    - Need more info
+ * Backend (low priority)
+ * Notifications (low priority)
    :maxdepth: 2
 
    devel/development
+   devel/plugins
 
 Autogenerated API docs
 ======================

docs/intro/features.rst

   - ajp
   - cgi (slow, not recommended)
 
+Plugins
+=======
+Moin is modular, many of the built in parts are implemented as plugins (or are in process of being rewriten as such).
+This means thats you can customize Moin without having to change core code.
+
+Some of already implemented and planed plugin types:
+
+* Authentication
+* Blueprints
+* Commandline scripts
+* Stores
+* Themes
+* Items
+* Mimetype support
+* Converters/Macros
+* Storage backends
+
 Authentication
 ==============
 * Builtin - username / password login form of moin, MoinAuth
 ============
 * html5, css, javascript with jquery, svg
 * python
-* flask, flask-cache, flask-babel, flask-themes, flask-script
+* flask, flask-cache, flask-babel, flask-script
 * whoosh, werkzeug, pygments, flatland, blinker, babel, emeraldtree
 * sqlalchemy (supports all popular SQL DBMS), sqlite, kyoto tycoon/cabinet