Merge pull request #40 from Flow-Launcher/update_python_docs

Update Python example plugin docs

Author: jjw24

py-develop-plugins.md

@@ -9,10 +9,10 @@ When building a Python plugins there are several things to be mindful of:
     2. Publish all as a zip- zip up your project including a lib directory that contains the modules and publish it to GitHub Releases page.
     3. Point your module imports to the lib directory- reference all the modules to that directory where they are first imported.
 
-* The user can use their own system installed Python with Flow Launcher. But in most circumstances the user will most likely be using Flow Launcher's own embedded Python executable. [Embedded Python](https://docs.python.org/3/using/windows.html#the-embeddable-package) is isolated from the users system and does not prepend the scripts run directory to the system `PATH`.<sup>[ref](https://bugs.python.org/issue28245)</sup> If you need to import external files please follow the example below.
+* User can use their own system installed Python with Flow Launcher. But in most circumstances they will most likely be using Flow Launcher's own embedded Python executable. [Embedded Python](https://docs.python.org/3/using/windows.html#the-embeddable-package) is isolated from the users system and does not prepend the scripts run directory to the system `PATH`.<sup>[ref](https://bugs.python.org/issue28245)</sup> If you need to import external files please follow the example below.
 
 ### Simple Example
-Have a look at this simple example plugin [here](https://github.com/Flow-Launcher/plugin-samples/tree/master/HelloWorldPython), notice it has a folder called '.github/workflows' and a file called 'Publish Release.yml'. This is the workflow file that GitHub Workflow uses to run the CICD for the project. Moving out of that folder you can go into the [main.py](https://github.com/Flow-Launcher/plugin-samples/blob/master/HelloWorldPython/plugin.json) file, this is the entry file for your plugin. Notice it has this code block:
+Have a look at this simple example plugin [here](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython), notice it has a folder called '.github/workflows' and a file called 'Publish Release.yml'. This is the workflow file that GitHub Workflow uses to run the CICD for the project. Moving out of that folder you can go into the [main.py](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython/blob/main/main.py) file, this is the entry file for your plugin. Notice it has this code block:
 ```python
 import sys,os
 parent_folder_path = os.path.abspath(os.path.dirname(__file__))

py-setup-project.md

@@ -1,5 +1,5 @@
 ### 1. Add GitHub workflow
-The workflow [file](https://github.com/Flow-Launcher/plugin-samples/blob/master/HelloWorldPython/.github/workflows/Publish%20Release.yml) will help build and deploy your project, it does the following things:
+The workflow [file](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython/blob/main/.github/workflows/Publish%20Release.yml) will help build and deploy your project, it does the following things:
 1. `workflow_dispatch:` gives you the option to manually run your workflow from the Actions section of your project
 2. On pushes to main, it will kick off the workflow but ignore the push if it's only changes made to the workflow file.
 ```yml
@@ -22,25 +22,25 @@ push:
     path: 'plugin.json'
     prop_path: 'Version'
 ```
-5. The 'Install dependencies' section is where you will do most of your CI work. Notice it installs the requirements.txt and outputs it with the `-t` parameter to the `./lib` folder. This tells pip to dump all the installed modules to the local lib folder which you will zip up along with your project using the `zip -r <NAME-OF-YOUR-PLUGIN>.zip . -x '*.git*'`, where you replace this `<NAME-OF-YOUR-PLUGIN>` with the name of your plugin.
+5. The 'Install dependencies' section is where you will do most of your CI work. Notice it installs the requirements.txt and outputs it with the `-t` parameter to the `./lib` folder. This tells pip to dump all the installed modules to the local lib folder which you will zip up along with your project using the `zip -r Flow.Launcher.Plugin.HelloWorldPython.zip . -x '*.git*'`, where you replace this `Flow.Launcher.Plugin.HelloWorldPython` with the name of your plugin.
 
     You can also add additional steps here to unpack/install any additional depedencies your plugin requires, for example compiling additional translation files like [this](https://github.com/deefrawley/Flow.Launcher.Plugin.Currency/blob/23770ee929af059b1b1b7f9b5f3327b692ac9587/.github/workflows/Publish%20Release.yml#L34)
 ```yml
 - name: Install dependencies
   run: |
     python -m pip install --upgrade pip
     pip install -r ./requirements.txt -t ./lib
-    zip -r <NAME-OF-YOUR-PLUGIN>.zip . -x '*.git*'
+    zip -r Flow.Launcher.Plugin.HelloWorldPython.zip . -x '*.git*'
 ```
 
 ### 2. Publish as zip
-The final step to the workflow file is this publish section, which will publish the zip file you generated, upload to GitHub Releases page and tag with the version generated from the previous step from your plugin.json file. Remmember again to replace `<NAME-OF-YOUR-PLUGIN>` with the name of your plugin.
+The final step to the workflow file is this publish section, which will publish the zip file you generated, upload to GitHub Releases page and tag with the version generated from the previous step from your plugin.json file. Remember again to replace `Flow.Launcher.Plugin.HelloWorldPython` with the name of your plugin.
 ```yml
 - name: Publish
-  if: success() && github.ref == 'refs/heads/main'
+  if: success()
   uses: softprops/action-gh-release@v1
   with:
-    files: '<NAME-OF-YOUR-PLUGIN>.zip'
+    files: 'Flow.Launcher.Plugin.HelloWorldPython.zip'
     tag_name: "v${{steps.version.outputs.prop}}"
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -58,4 +58,4 @@ sys.path.append(os.path.join(parent_folder_path, 'lib'))
 sys.path.append(os.path.join(parent_folder_path, 'plugin'))
 
 ```
-Add the above code into your init file at the top, usually this is the [main.py](https://github.com/Flow-Launcher/plugin-samples/blob/master/HelloWorldPython/main.py) file. This block of code appends the path of your lib and plugin directories on the user's machine to `sys.path`. `sys.path` is a built-in variable within the sys module, which contains a list of directories that the Python interpreter will search in for the required module. Effectively we are telling the interpreter if the required modules in your plugin are not found among its built-in modules then look through the list of directories defined by sys.path, which should have all the modules installed by your GitHub workflow in the 'lib' folder.
+Add the above code into your init file at the top, usually this is the [main.py](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython/blob/main/main.py) file. This block of code appends the path of your lib and plugin directories on the user's machine to `sys.path`. `sys.path` is a built-in variable within the sys module, which contains a list of directories that the Python interpreter will search in for the required module. Effectively we are telling the interpreter if the required modules in your plugin are not found among its built-in modules then look through the list of directories defined by sys.path, which should have all the modules installed by your GitHub workflow in the 'lib' folder.

py-write-code.md

@@ -13,6 +13,7 @@ sys.path.append(os.path.join(parent_folder_path, 'lib'))
 sys.path.append(os.path.join(parent_folder_path, 'plugin'))
 
 from flowlauncher import FlowLauncher
+import webbrowser
 
 
 class HelloWorld(FlowLauncher):
@@ -21,27 +22,30 @@ class HelloWorld(FlowLauncher):
         return [
             {
                 "Title": "Hello World, this is where title goes. {}".format(('Your query is: ' + query , query)[query == '']),
-                "SubTitle": "This is where your subtitle goes",
+                "SubTitle": "This is where your subtitle goes, press enter to open Flow's url",
                 "IcoPath": "Images/app.png",
                 "JsonRPCAction": {
-                    "method": "do_something_for_query",
-                    "parameters": [param1, param2]
+                    "method": "open_url",
+                    "parameters": ["https://github.com/Flow-Launcher/Flow.Launcher"]
                 }
-                "ContextData": "ctxData",
             }
         ]
 
     def context_menu(self, data):
         return [
             {
-                "Title": "Context menu entry",
-                "SubTitle": "Data: {}".format(data),
-                "IcoPath": "Images/app.ico",
+                "Title": "Hello World Python's Context menu",
+                "SubTitle": "Press enter to open Flow the plugin's repo in GitHub",
+                "IcoPath": "Images/app.png",
+                "JsonRPCAction": {
+                    "method": "open_url",
+                    "parameters": ["https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython"]
+                }
             }
         ]
 
-    def do_something_for_query(self, param1, param2):
-        pass
+    def open_url(self, url):
+        webbrowser.open(url)
 
 if __name__ == "__main__":
     HelloWorld()
@@ -59,14 +63,14 @@ This is the main entry to your plugin and the return block will be a list of the
 **JsonRPCAction**
 
 This is where you specify the method that will be executed when the user selects on the result.
-In this example, if the user selects the result, the `do_something_for_query` method will be called with the two parameters, it is then up to you to define what you want the method to do.
+In this example, if the user selects the result, the `open_url` method will be called with the url parameter that opens the Flow Launcher GitHub repo.
 
 ### 5. Create an additional context menu
 **def context_menu(self, data):**
 
-This method creates a context menu for your results, where the user can carry out additional tasks when the go to the context menue via pressing `Shift + Enter`. A context menu could be helpful if you want some tasks specific to your returned results, for example the Explorer plugin would return a list of file results, and when going to the context menu of one of the result users can select to copy the file. 
+This method creates a context menu for your results, where the user can carry out additional tasks when they go to the context menue via pressing `Shift + Enter`. A context menu could be helpful if you want some tasks specific to your returned results, for example the Explorer plugin would return a list of file results, and when going to the context menu of one of the result users can select to copy the file.
 
-To attach a method to your context menu result, do the same as for normal results where you define a JsonRPCAction item with the method and parameters you want to call and pass through.
+To attach a method to your context menu result, do the same as for normal results where you define a JsonRPCAction item with the method and parameters you want to call and pass through. In this case the context menu will simply open the HelloWorldPython plugin's GitHub repo.
 
 ### 6. Your plugin.json