Documentation #7

meluru · 2017-04-20T12:14:58Z

API documentation is still WIP but it would be great if you could already check the installation, setup and example usage steps if they make sense.

meluru · 2017-04-24T13:15:11Z

Api documentation updated, let me know if I should add something more to it.

nop33

Good job 👍 It's mainly syntactical mistakes, but the documentation looks great!

nop33 · 2017-04-25T11:36:38Z

docs/source/index.rst

+Creating a plugin
+-----------------
+
+Creating a plugin is simple. First of all you need to create a class for your plugin inheriting from Plugin::


Shouldn't we also mention the file names? Does it play an important role? Like plugin.py, setup.py, etc. If not, nvm!

A folder structure would also be useful. If I start creating the plugin now for example, just by reading the doc, I have no idea how to structure the code you mentioned 😉

nop33 · 2017-04-25T11:38:45Z

docs/source/index.rst

+Current plugin
+--------------
+
+Very useful feature of Flask-PluginEngine is a ``current_plugin`` global value. It's a proxy to currently active plugin.


"Very useful feature of Flask-PluginEngine is a the..."

"It's a proxy to the currently active plugin."

nop33 · 2017-04-25T12:19:47Z

docs/source/index.rst

+Example plugin functionality
+----------------------------
+
+Now let's give our plugin some functionality to show how you can use the plugin. In this example we will render plugin's template from our application.


"Now let's give our plugin some functionality to show how you can use ~~the plugin~~ it. In this example we will render the plugin's template from our application."

nop33 · 2017-04-25T12:32:25Z

docs/source/index.rst

+
+Now let's give our plugin some functionality to show how you can use the plugin. In this example we will render plugin's template from our application.
+
+Let's create the templates folder with a simple Jinja template. For example displaying plugin's title and description::


"Let's create the templates folder with a simple Jinja template ~~. For example displaying~~ to display for example the plugin's title and description"

nop33 · 2017-04-25T12:34:10Z

docs/source/index.rst

+        <div>{{ plugin.description }}</div>
+    {% endblock %}
+
+If you documented plugin's class now you can access it as a ``name`` and ``description`` class properties.


I am afraid I don't understand what this means.

nop33 · 2017-04-25T12:57:47Z

docs/source/index.rst

+---------------------------------
+
+To understand the possibilities of Flask-PluginEngine we will create a Jinja template, where we will list all the plugins we are using.
+Let's create two templates, the base one (base.html), for example::


I'd reword it a bit to:
"Let's create two templates, base.html and index.html: " and add comments above each code block below, like this:

{# base.html #} <!DOCTYPE html> <html lang="en"> <head> ...

{# index.html #} <!DOCTYPE html> <html lang="en"> <head> ...

nop33 · 2017-04-25T12:59:52Z

docs/source/index.rst

+    def hello():
+    return render_template('index.html', plugins=active_plugins)
+
+Now what we also should do is register the blueprints of all our plugins, for instance::


"Now what we should also do is to register the blueprints of all our plugins..."

nop33 · 2017-04-25T13:01:14Z

docs/source/index.rst

+    if __name__ == "__main__":
+        app.run()
+
+Now when we will go to the index page of our application we will be able to access plugin's template.


"Now, when we ~~will~~ go to the index page of our application we ~~will be able to~~ can access the plugin's template."

nop33 · 2017-04-25T13:01:49Z

docs/source/index.rst

+
+Now when we will go to the index page of our application we will be able to access plugin's template.
+
+You can find the application in the source code in example folder.


"You can find the source code of the application in the example folder"

nop33 · 2017-04-25T13:02:49Z

docs/source/index.rst

+
+    .. classmethod:: title()
+
+        Plugin's title from the docstring


Isn't this supposed to be fetched automatically?

It should be, but due to the decorator problem I had to write it

meluru · 2017-04-26T14:31:38Z

Updated

coveralls · 2017-04-26T14:36:56Z

Coverage remained the same at 87.321% when pulling 04467d9 on meluru:documentation into 14c7b97 on indico:master.

mvidalgarcia

Well done! 🎉

mvidalgarcia · 2017-04-27T13:16:17Z

docs/source/index.rst

+    |   setup.py
+    |
+    └───templates
+        |   index.html


This directory tree is a bit confusing IMO, what about this?

plugin ├── example_plugin.py ├── setup.py └── templates └── index.html

mvidalgarcia · 2017-04-27T13:28:43Z

docs/source/index.rst

+    from flask_pluginengine import Plugin
+
+    class ExamplePlugin(Plugin):
+    """ExamplePlugin


The docstring here should be indented.

mvidalgarcia · 2017-04-27T13:28:47Z

docs/source/index.rst

+        <div>{{ plugin.description }}</div>
+    {% endblock %}
+
+Notice that the template extends a base.html. We are going to use the application's base template.


base.html

mvidalgarcia · 2017-04-27T13:28:50Z

docs/source/index.rst

+
+    @plugin_blueprint.route('/plugin')
+    def hello_plugin():
+    return render_template('example_plugin:index.html', plugin=current_plugin)


Indentation.

mvidalgarcia · 2017-04-27T13:42:38Z

docs/source/index.rst

+
+    @app.route("/")
+    def hello():
+    return render_template('index.html', plugins=active_plugins)


Indentation.

mvidalgarcia · 2017-04-27T13:42:55Z

docs/source/index.rst

+Now what we should also do is to register the blueprints of all our plugins, for instance::
+
+    for plugin in active_plugins:
+    with plugin.plugin_context():


Indentation.

mvidalgarcia · 2017-04-27T13:44:56Z

docs/source/index.rst

+    <html lang="en">
+        <head>
+            <meta charset="UTF-8">
+            <title>Title</title>


Perhaps it would look better "Flask-PluginEngine example" or similar?

mvidalgarcia · 2017-04-27T14:09:06Z

docs/source/index.rst

+    if __name__ == "__main__":
+        app.run()
+
+Now when we go to the index page of our application we can access the plugin's template.


Maybe it's worth to mention here that you can also go to /plugin and access the template of the plugin itself via its blueprint so that you prove that the stuff implemented in the plugin can be used.

mvidalgarcia · 2017-04-27T14:09:47Z

docs/source/index.rst

+
+Now when we go to the index page of our application we can access the plugin's template.
+
+You can find the source code of the application in the example folder.


I'd appreciate here a link to the example folder.

mvidalgarcia · 2017-04-27T14:16:02Z

docs/source/index.rst

+    active_plugins = plugin_engine.get_active_plugins(app=app).values()
+
+
+Example application functionality


When I started reading this section I didn't know where to write the fragments of code explained and I struggled a bit until I check the example folder. In my opinion would be useful here to either explain that the plugin will be in a separated folder and the app itself in a different one or show again a directory tree pointing where the code in this section should be written in.

meluru · 2017-04-28T09:16:19Z

Updated

DavidAndreev

I couldn't find anything else :) Great job ! Nice guide which is easy to understand ;)

DavidAndreev · 2017-05-02T15:13:55Z

docs/source/index.rst

@@ -26,17 +26,29 @@ You can install Flask-PluginEngine with the following command::
 Creating a plugin
 -----------------

-Creating a plugin is simple. First of all you need to create a class for your plugin inheriting from Plugin::
+Creating a plugin is simple. First of all you need to create necessary files: file for your plugin code (in our case: ``example_plugin.py``), ``setup.py`` and


I think there should be a coma : First of all, you need ..

pferreir

Great work, just have a few suggestions!

pferreir · 2017-05-03T14:22:43Z

docs/source/index.rst

+Creating a plugin
+-----------------
+
+Creating a plugin is simple. First of all you need to create necessary files: file for your plugin code (in our case: ``example_plugin.py``), ``setup.py`` and


"create the necessary files: a file for [...] and a templates folder"

pferreir · 2017-05-03T14:24:26Z

docs/source/index.rst

+        Just an example plugin
+        """
+
+Second, you need to fill the ``setup.py``. It's important to define a proper entry point to plugin's class. For example::


"point to the plugin's class"

pferreir · 2017-05-03T14:27:16Z

docs/source/index.rst

+    def hello_plugin():
+        return render_template('example_plugin:index.html', plugin=current_plugin)
+
+We can render any plugin template inside our application specifying the name of the plugin before the template name in ``render_template`` function, like above.


"in the render_template function"

pferreir · 2017-05-03T14:27:43Z

docs/source/index.rst

+        return render_template('example_plugin:index.html', plugin=current_plugin)
+
+We can render any plugin template inside our application specifying the name of the plugin before the template name in ``render_template`` function, like above.
+We are also passing a current_plugin object to the template.


I would add double backticks around current_plugin.

pferreir · 2017-05-03T14:38:06Z

docs/source/index.rst

+Minimal application setup
+-------------------------
+
+To create a Flask application using Flask-PluginEngine we need to define it as ``PluginFlask`` application::


"as a PluginFlask application"

pferreir · 2017-05-03T14:38:32Z

docs/source/index.rst

+
+    if __name__ == "__main__":
+        app.run()
+


I would maybe mention that PluginFlask is just a regular Flask application object with some added plugin magic. It should be already quite clear, however.

pferreir · 2017-05-03T14:39:59Z

docs/source/index.rst

+        name='Example-Plugin',
+        version='0.0.1',
+        py_modules=['example_plugin'],
+        entry_points={'example': {'example_plugin = example_plugin:ExamplePlugin'}}


I would mention that example is the namespace we're going to use below, in the application's config.

pferreir · 2017-05-03T14:41:12Z

docs/source/index.rst

+    plugin_engine.load_plugins(app)
+
+Then, we can access the loaded plugins by calling the :func:`get_active_plugins` method, which will return a dictionary containing the active plugins.
+To check if all of the plugins were loaded correctly we can also call the :func:`get_failed_plugins` method that will return a dictionary with plugins that failed to load::


I would perhaps move the part about get_failed_plugins below the example. It's a bit confusing to have an example that doesn't refer to it.

meluru · 2017-05-04T13:13:44Z

Updated

ThiefMaster · 2017-05-09T12:17:17Z

Would it make sense to split the docs into multiple pages? When you want to write a plugin for some application you probably don't care about how to use this extension in your own app. OTOH, an application should have its own documentation on how to write plugins for it.

ThiefMaster · 2017-05-09T12:13:38Z

docs/source/index.rst

+
+        The Plugin instance used by the current app
+
+    .. classmethod:: title()


Does it show up as title() or title in the docs? Because it's a class-level property and using () wouldn't work for obvious reasons ;)

Just checked and it indeed shows up wrong.

ThiefMaster · 2017-05-09T12:13:52Z

example/app/app.py

+        app.register_blueprint(plugin.get_blueprint())
+
+
+@app.route("/")


single quotes

ThiefMaster · 2017-05-09T12:13:56Z

example/app/app.py

+    return render_template('index.html', plugins=active_plugins)
+
+
+if __name__ == "__main__":


single quotes

ThiefMaster · 2017-05-09T12:14:22Z

flask_pluginengine/plugin.py

@@ -119,12 +119,14 @@ def instance(cls):
    @classproperty
    @classmethod
    def title(cls):
+        """Plugin's title from the docstring"""


"""The title of the plugin. Automatically retrieved from the docstring of the plugin class. """

ThiefMaster · 2017-05-09T12:14:31Z

flask_pluginengine/plugin.py

        parts = trim_docstring(cls.__doc__).split('\n', 1)
        return parts[0].strip()

    @classproperty
    @classmethod
    def description(cls):
+        """Plugin's description from the docstring"""


"""The description of the plugin. Automatically retrieved from the docstring of the plugin class. """

meluru · 2017-05-10T15:12:16Z

Updated

coveralls · 2017-05-15T12:30:51Z

Coverage remained the same at 87.321% when pulling e2922fd on meluru:documentation into c1d7234 on indico:master.

nop33 suggested changes Apr 25, 2017

View reviewed changes

mvidalgarcia suggested changes Apr 27, 2017

View reviewed changes

meluru force-pushed the documentation branch from 04467d9 to 8701c5f Compare April 28, 2017 09:15

DavidAndreev reviewed May 2, 2017

View reviewed changes

pferreir requested changes May 3, 2017

View reviewed changes

meluru force-pushed the documentation branch from 8701c5f to d279449 Compare May 4, 2017 13:08

ThiefMaster requested changes May 9, 2017

View reviewed changes

Natalia Juszka added 4 commits May 10, 2017 17:09

Add example app with plugin

16f11cf

Add basic documentation

1d472a3

Add API documentation

4915287

Improve documentation

1ad5a91

meluru force-pushed the documentation branch from d279449 to 1ad5a91 Compare May 10, 2017 15:11

Natalia Juszka added 2 commits May 12, 2017 14:43

Add logo

d41b688

Add index logo

e2922fd

pferreir approved these changes May 15, 2017

View reviewed changes

meluru merged commit 112a39d into indico:master May 15, 2017

meluru deleted the documentation branch May 15, 2017 12:40


		Now let's give our plugin some functionality to show how you can use the plugin. In this example we will render plugin's template from our application.

		Let's create the templates folder with a simple Jinja template. For example displaying plugin's title and description::


		Now when we will go to the index page of our application we will be able to access plugin's template.

		You can find the application in the source code in example folder.


		Now when we go to the index page of our application we can access the plugin's template.

		You can find the source code of the application in the example folder.

		active_plugins = plugin_engine.get_active_plugins(app=app).values()


		Example application functionality


		The Plugin instance used by the current app

		.. classmethod:: title()

		app.register_blueprint(plugin.get_blueprint())


		@app.route("/")

		return render_template('index.html', plugins=active_plugins)


		if __name__ == "__main__":

Documentation #7

Documentation #7

Conversation

meluru commented Apr 20, 2017

meluru commented Apr 24, 2017

nop33 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

meluru commented Apr 26, 2017

coveralls commented Apr 26, 2017 • edited

mvidalgarcia left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

meluru commented Apr 28, 2017

DavidAndreev left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pferreir left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

meluru commented May 4, 2017

ThiefMaster commented May 9, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

meluru commented May 10, 2017

coveralls commented May 15, 2017 • edited

coveralls commented Apr 26, 2017 •

edited

coveralls commented May 15, 2017 •

edited