doc for crypter plugin

2 files changed, 55 insertions, 18 deletions

diff --git a/docs/plugins/base_plugin.rst b/docs/plugins/base_plugin.rst
index e3c72994b..1849f3986 100644
--- a/docs/plugins/base_plugin.rst
+++ b/docs/plugins/base_plugin.rst
@@ -17,11 +17,15 @@ An overview of acceptible values can be found in :class:`Base <module.plugins.Ba
 Non needed attributes can be left out, except ``__version__``. Nevertheless please fill out most information
 as you can, when you want to submit your plugin to the public repo.
 
+Additionally :class:`Crypter <module.plugins.Crypter.Crypter>` and :class:`Crypter <module.plugins.Hoster.Hoster>`
+needs to have a specific regexp [1]_ ``__pattern__``. This will be matched against input urls and if a suited
+plugin is found it is selected to handle the url.
+
 You don't need to subclass :class:`Base <module.plugins.Base.Base>` directly, but the
 intermediate type according to your plugin. As example we choose an Hoster plugin, but the same is true for all
 plugin types.
 
-For localization pyLoad supports gettext [1]_, to mark strings for translation surround them with ``_("...")``.
+For localization pyLoad supports gettext [2]_, to mark strings for translation surround them with ``_("...")``.
 
 How basic hoster plugin header could look like::
 
@@ -34,6 +38,8 @@ How basic hoster plugin header could look like::
                 is not needed for hoster plugin,
                 but hook plugin should have it so the user knows what they doing.""")
 
+In future examples the meta data will be left out, but remember it's required in every plugin!
+
 Config Entries
 --------------
 
@@ -96,13 +102,14 @@ To enable debugging functionality start pyLoad with ``-d`` option or enable it i
 You should use ``self.logDebug(msg)`` when ever it is reasonable. It is a good pratice to log server output
 or the calculation of results and then check in the log if it really it what you are expecting.
 
-For further debugging you can install ipython [2]_, and set breakpoints with ``self.core.breakpoint()``.
-It will open the python debugger [3]_ and pause the plugin thread.
+For further debugging you can install ipython [3]_, and set breakpoints with ``self.core.breakpoint()``.
+It will open the python debugger [4]_ and pause the plugin thread.
 To open a ipython shell in the running programm use ``self.shell()``.
 These methods are usefull to gain access to the code flow at runtime and check or modify variables.
 
 
 .. rubric:: Footnotes
-.. [1] http://docs.python.org/library/gettext.html
-.. [2] http://ipython.org/
-.. [3] http://docs.python.org/library/pdb.html
\ No newline at end of file
+.. [1] http://docs.python.org/library/re.html
+.. [2] http://docs.python.org/library/gettext.html
+.. [3] http://ipython.org/
+.. [4] http://docs.python.org/library/pdb.html
\ No newline at end of file
diff --git a/docs/plugins/crypter_plugin.rst b/docs/plugins/crypter_plugin.rst
index 639d58abf..1497ced07 100644
--- a/docs/plugins/crypter_plugin.rst
+++ b/docs/plugins/crypter_plugin.rst
@@ -3,23 +3,53 @@
 Crypter - Extract links from pages
 ==================================
 
-What about Decrypter and Container plugins?
-Well, they work nearly the same, only that the function they have to provide is named ``decrypt``
-
-Example: ::
+We are starting with the simplest plugin, the :class:`Crypter <module.plugins.Crypter.Crypter>`.
+It's job is it to take a url as input and generate new package or links, for example by filtering the urls or
+loading a page and extracting links from the html code. You need to define the ``__pattern__`` to match
+target urls and subclass from :class:`Crypter <module.plugins.Crypter.Crypter>`. ::
 
     from module.plugin.Crypter import Crypter
 
     class MyFileCrypter(Crypter):
-        """
-            plugin code
-        """
-        def decrypt(self, pyfile):
+        __pattern__ = r"mycrypter.com/id/([0-9]+)"
+
+        def decryptURL(self, url):
 
             urls = ["http://get.pyload.org/src", "http://get.pyload.org/debian", "http://get.pyload.org/win"]
+            return urls
+
+You have to overwrite at least one of ``.decryptFile``, ``.decryptURL``, ``.decryptURLs``. The first one
+is only useful for container files, whereas the last is usefull when it's possible to handle a bunch of urls
+at once. If in doubt, just overwrite `decryptURL`.
+
+Generating Packages
+-------------------
+
+When finished with decrypting just return the urls as list and they will be added to the package. You can also
+create new Packages if needed by instantiating a :class:`Package` instance, which will look like the following::
+
+    from module.plugin.Crypter import Crypter, Package
+
+    class MyFileCrypter(Crypter):
+
+        def decryptURL(self, url):
+
+            html = self.load(url)
+
+            # .decrypt_from_content is only a example method here and will return a list of urls
+            urls = self.decrypt_from_content(html)
+            return Package("my new package", urls)
+
+And that's basically all you need to know. Just as little side-note if you want to use decrypter in
+your code you can use::
+
+        plugin = self.core.pluginManager.loadClass("crypter", "NameOfThePlugin")
+        # decrypted will be a list of urls
+        decrypted = plugin.decrypt(urls)
 
-            self.packages.append(("pyLoad packages", urls, "pyLoad packages")) # urls list of urls
+Testing
+-------
 
-They can access all the methods from :class:`Plugin <module.plugins.Plugin.Plugin>`, but the important thing is they
-have to append all packages they parsed to the `self.packages` list. Simply append tuples with `(name, urls, folder)`,
-where urls is the list of urls contained in the packages. Thats all of your work, pyLoad will know what to do with them.
+Please append a test link at :file:`tests/crypterlinks.txt` followed by `||xy`, where xy is the number of
+expected links/packages to extract.
+Our testrunner will be able to check your plugin periodical for functionality.
\ No newline at end of file