Merge pull request Sylius#7858 from lchrusciel/extension-docs

[Documentation] Describe Sylius plugins
ezecosystem · Mar 30, 2017 · 320bd2b · 320bd2b
2 parents f2d5c99 + 4ec0c71
commit 320bd2b
Show file tree

Hide file tree

Showing 11 changed files with 128 additions and 110 deletions.
diff --git a/docs/book/orders/payments.rst b/docs/book/orders/payments.rst
@@ -121,7 +121,7 @@ Other Payment Gateways
     Learn more about integrating payment gateways in `the Payum docs <https://github.com/Payum/Payum/blob/master/docs/index.md>`_.
 
 When the Payment Gateway you are trying to use does have a bridge available and you integrate them on your own,
-use our guide on :doc:`extension development </extensions/creating-extension>`.
+use our guide on :doc:`extension development </plugins/creating-plugin>`.
 
 .. tip::
 

diff --git a/docs/customization/template.rst b/docs/customization/template.rst
@@ -26,7 +26,7 @@ Methods of templates customizing
 
     The second method is **templates customization via events**. You are able to listen on these template events,
     and by that add your own blocks without copying and pasting the whole templates. This feature is really useful
-    when :doc:`creating Sylius Extensions </extensions/creating-extension>`.
+    when :doc:`creating Sylius Extensions </plugins/creating-plugin>`.
 
 How to customize templates by overriding?
 -----------------------------------------

diff --git a/docs/extensions/creating-extension.rst b/docs/extensions/creating-extension.rst
diff --git a/docs/extensions/index.rst b/docs/extensions/index.rst
diff --git a/docs/extensions/list.rst b/docs/extensions/list.rst
diff --git a/docs/extensions/map.rst.inc b/docs/extensions/map.rst.inc
diff --git a/docs/index.rst b/docs/index.rst
@@ -139,17 +139,17 @@ Components
 
 .. include:: /components/map.rst.inc
 
-Sylius Extensions
------------------
+Sylius Plugins
+--------------
 
-The collection of Sylius Extensions together with the guide on Extensions development.
+The collection of Sylius Plugins together with the guide on Plugins development.
 
 .. toctree::
    :hidden:
 
-   extensions/index
+   plugins/index
 
-.. include:: /extensions/map.rst.inc
+.. include:: /plugins/map.rst.inc
 
 The Contribution Guide
 ----------------------

diff --git a/docs/plugins/creating-plugin.rst b/docs/plugins/creating-plugin.rst
@@ -0,0 +1,69 @@
+How to create a plugin for Sylius?
+==================================
+
+Sylius plugin is nothing more but a regular Symfony bundle adding custom behaviour to the default Sylius application.
+
+The best way to create your own plugin is to use `Sylius plugin skeleton <https://github.com/Sylius/PluginSkeleton>`_,
+which has built-in infrastructure for designing and testing using `Behat`_.
+
+1. Create project using Composer.
+---------------------------------
+
+.. code-block:: bash
+
+    $ composer create-project sylius/plugin-skeleton MyPlugin
+
+.. note::
+
+    The plugin can be created anywhere, not only inside Sylius application, because it already has the test environment inside.
+
+2. Get familiar with basic plugin design.
+-----------------------------------------
+
+The skeleton comes with simple application that greets a customer. There are feature scenarios in ``features`` directory;
+exemplary bundle with a controller, a template and a routing configuration in ``src``;
+and the testing infrastructure in ``tests``.
+
+.. note::
+
+    The ``tests/Application`` directory contains a sample Symfony application used to test your plugin.
+
+3. Remove boilerplate files and rename your bundle.
+---------------------------------------------------
+
+In most cases you don't want your Sylius plugin to greet customer like it is now, so feel free to remove unnecessary
+controllers, assets and features. You will also want to change the plugin's namespace from ``Acme\ExamplePlugin`` to a
+more meaningful one. Keep in mind that these changes also need to be done in ``tests/Application`` and ``composer.json``.
+
+4. Implement your awesome features.
+-----------------------------------
+
+Looking at existing Sylius plugins like `Lakion\SyliusCmsBundle <https://github.com/Lakion/SyliusCmsBundle>`_
+or `Lakion\SyliusElasticSearchBundle <https://github.com/Lakion/SyliusElasticSearchBundle>`_ is
+a great way to start developing your own plugins.
+
+Feel free to use `BDD <https://www.agilealliance.org/glossary/bdd/>`_ with `Behat`_, `phpspec`_ and `PhpUnit`_
+to ensure your plugin's extraordinary quality.
+
+.. tip::
+
+    For the plugins, the suggested way of modifying Sylius is using :doc:`the Customization Guide </customization/index>`.
+    There you will find a lot of help while trying to modify templates, state machines, controllers and many, many more.
+
+.. _`Behat`: http://behat.org/en/latest/
+.. _`phpspec`: http://www.phpspec.net/en/stable/
+.. _`PHPUnit`: https://phpunit.de/
+
+5. Naming conventions
+---------------------
+
+Besides the way you are creating plugins (based on our skeleton or on your own), there are a few naming conventions that should be followed:
+
+ * Bundle class must have a `Plugin` suffix instead of `Bundle` in its name (e.g. InvoicePlugin).
+ * Bundle class must use the `Sylius\Bundle\CoreBundle\Application\SyliusPluginTrait`.
+ * The name of the extension in DependencyInjection folder must follow the regular Symfony rules (e.g. InvoiceExtension).
+ * The plugin shouldn't have Sylius prefix in its name. `Plugin` suffix in terms of bundles is unique for Sylius at the moment.
+
+The following rules are applied to all bundles which will provide an integration with the whole Sylius platform
+(`sylius/sylius` or `sylius/core-bundle` in vendors). Reusable components for the whole Symfony community, which will be based
+just on some Sylius bundles should follow regular Symfony conventions.
diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
@@ -0,0 +1,35 @@
+Sylius Plugins
+==============
+
+Sylius as a platform has a lot of space for various customizations and extensions. It aims to provide a simple schema for
+developing plugins. Anything you can imagine can be implemented and added to the Sylius framework as a plugin.
+
+.. toctree::
+    :hidden:
+
+    creating-plugin
+    list
+
+What are the plugins for?
+-------------------------
+
+The plugins are Symfony Bundles that either modify or extend Sylius default behaviour, providing useful features that
+are built on top of the Sylius Core.
+
+Exemplary features may be: Social media buttons, newsletter, wishlists etc.
+
+Plugin Development Flow
+-----------------------
+
+Since Sylius is an open-source platform, there is a certain flow in order for the plugin to become officially adopted by the community.
+
+**1.** Develop the plugin using :doc:`the official Plugin Development guide </plugins/creating-plugin>`.
+
+**2.** Send it to the project maintainers. It can be via email to any member of the Sylius Core team, or `the official Sylius Slack <https://slackinvite.me/to/sylius-devs>`_.
+
+**3.** Wait for your Plugin to be featured in :doc:`the list of plugins </plugins/list>` here in the docs and on the Sylius website.
+
+Learn more
+----------
+
+.. include:: /plugins/map.rst.inc
diff --git a/docs/plugins/list.rst b/docs/plugins/list.rst
@@ -0,0 +1,15 @@
+Sylius Plugins List
+===================
+
+.. note::
+
+    This section will grow whenever a new plugin will be provided by the Sylius open-source community!
+
+The current list of Sylius Plugins presents as follows:
+
+.. warning::
+
+    Following plugins have been developed before adopting the Plugins naming convention. They will be renamed in the nearest future.
+
+* `Lakion\SyliusCmsBundle <https://github.com/Lakion/SyliusCmsBundle>`_
+* `Lakion\SyliusElasticSearchBundle <https://github.com/Lakion/SyliusElasticSearchBundle>`_
diff --git a/docs/plugins/map.rst.inc b/docs/plugins/map.rst.inc
@@ -0,0 +1,2 @@
+* :doc:`/plugins/creating-plugin`
+* :doc:`/plugins/list`