Merge pull request #27 from Flow-Launcher/update_py_docs

update Python plugin documentation

Author: jjw24

_sidebar.md

@@ -6,10 +6,13 @@
     - Dotnet Plugins
       - [**Development Guide**](/develop-dotnet-plugins.md)
       - [**API Reference**](API-Reference/)
-    - JSONRPC Plugins
+    - Python Plugins
+      - [**Before you start**](/py-develop-plugins.md) 
+      - [**Set up your project**](/py-setup-project.md)
+      - [**Write the code**](/py-write-code.md)
+      - [**Add your plugin to Flow**](/py-release-project.md)
+      - [**Plugin references**](/py-plugin-references.md)
+    - JSONRPC
       - [**JSON RPC Introduction**](/json-rpc.md)
-      - [**Develop Python Plugins**](/develop-py-plugins.md)
     - [**Porting Plugins**](/port-plugins.md)
-
 - [**How To Create a Theme**](/how-to-create-a-theme.md)
-

develop-py-plugins.md

@@ -3,7 +3,7 @@
 ### Notes
 
 - When porting, please keep the author's commit history
-- Flow Launcher targets .Net Core 3.1, so plugins should also be upgraded to keep the continuity of future developments
+- Flow Launcher targets .Net 5, so plugins should also be upgraded to keep the continuity of future developments
 - All dll libraries used by the plugin should be outputted and included in the final build, to do this, set the attribute CopyLocalLockFileAssemblies in your project file to true
 
 ### Steps
@@ -12,7 +12,7 @@
 2. Use try convert tool from https://github.com/dotnet/try-convert
 3. Try-convert -w path-to-folder-or-solution-or-project
 4. May need to fix on the project file, a good template to follow is the [Explorer plugin](https://github.com/Flow-Launcher/Flow.Launcher/blob/dev/Plugins/Flow.Launcher.Plugin.Explorer/Flow.Launcher.Plugin.Explorer.csproj) project:
-	- fix <TargetFramework> to netcoreapp3.1
+	- fix <TargetFramework> to net5.0-windows
 	- set the output location as 'Output\Release\<name of the project>'
 	- add `<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>` and `<AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>` to the csproj file
 	- bump version to 2.0.0 and fix up any missing attributes if neccessary

port-plugins.md

@@ -0,0 +1,22 @@
+### About Flow's Python plugins
+
+Python plugins use the [JSON-RPC](https://flow-launcher.github.io/docs/#/json-rpc) protocol to communicate with Flow via JSON structured calls.
+
+When building a Python plugins there are several things to be mindful of:
+
+* The most important thing is we do not expect users to have to manually install the dependencies in requirements.txt because we aim to provide a seamless experience for them. This can be achieved by adding the following three things to your project:
+    1. Add a GitHub workflow- use a GitHub workflow that will install all your plugin's depedencies including the Python flowlauncher module to a folder called Lib inside your plugin.
+    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.
+
+### 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:
+```python
+import sys,os
+parent_folder_path = os.path.abspath(os.path.dirname(__file__))
+sys.path.append(parent_folder_path)
+sys.path.append(os.path.join(parent_folder_path, 'lib'))
+sys.path.append(os.path.join(parent_folder_path, 'plugin'))
+```

py-develop-plugins.md

@@ -0,0 +1,8 @@
+### Good references to follow
+
+Here are some plugins which could help you build out your own or serve as a reference point:
+- IsPrime https://github.com/lvonkacsoh/Flow.Launcher.Plugin.IsPrime
+- RollDice https://github.com/lvonkacsoh/Flow.Launcher.RollDice
+- FancyEmoji https://github.com/Ma-ve/Flow.Launcher.Plugin.FancyEmoji
+- Steam Search https://github.com/Garulf/Steam-Search
+- Currency Converter https://github.com/deefrawley/Flow.Launcher.Plugin.Currency

py-plugin-references.md

@@ -0,0 +1,2 @@
+### Release your plugin to Flow's Plugin Store 
+When you are ready to release your plugin for people to enjoy, simply head over to Flow's [plugin repo](https://github.com/Flow-Launcher/Flow.Launcher.PluginsManifest) and follow the instructions there in the readme.

py-release-project.md

@@ -0,0 +1,61 @@
+### 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:
+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
+push:
+    branches: [ main ]
+    paths-ignore: 
+      - .github/workflows/*
+```
+3. It specifies the python version that will be used for building your project:
+```yml
+    env:
+      python_ver: 3.8
+```
+4. The project's release version is obtained from your plugin.json automatically by the ci, so when built it will be appended to the zip file later:
+```yml
+- name: get version
+  id: version
+  uses: notiz-dev/github-action-json-property@release
+  with: 
+    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.
+    
+    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*'
+```
+
+### 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.
+```yml
+- name: Publish
+  if: success() && github.ref == 'refs/heads/main'
+  uses: softprops/action-gh-release@v1
+  with:
+    files: '<NAME-OF-YOUR-PLUGIN>.zip'
+    tag_name: "v${{steps.version.outputs.prop}}"
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Feel free to also have a read of this [blog post](https://blog.ipswitch.com/how-to-build-your-first-github-actions-workflow) which does a simple explaination of how to use GitHub Actions Workflow.
+
+### 3. Use lib directory
+Once the lib folder is included in your zip release, it can then be used without needing the user to manually pip install. You just have to tell during runtime to find those modules in your local lib folder. Do this by using this exact copy of the following block of code:
+```python
+import sys,os
+parent_folder_path = os.path.abspath(os.path.dirname(__file__))
+sys.path.append(parent_folder_path)
+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.

py-setup-project.md

@@ -0,0 +1,77 @@
+### 1. Start with a branch
+Since we have created a CI for your plugin in the [previous step](https://flow-launcher.github.io/docs/#/py-setup-project), which includes creating a release when you push/merge to the 'main' branch, it is then neccessary to create another git branch separate to your 'main' branch so you can continue to work on your plugin with git commits and pushes without creating a new release each time.
+
+It is a good practice that you create a branch for each of the new feature/fixes you are releasing for your plugin, if you are not sure how to do so then follow this [video tutorial](https://www.gitkraken.com/learn/git/problems/create-git-branch). Once you have fully finished developing your plugin with your new branch, then you can merge it into the 'main' branch, which will consequently create a new release for your plugin with a version from your `plugin.json`.
+
+### 2. main.py
+your main.py should look something like below:
+```
+import sys,os
+parent_folder_path = os.path.abspath(os.path.dirname(__file__))
+sys.path.append(parent_folder_path)
+sys.path.append(os.path.join(parent_folder_path, 'lib'))
+sys.path.append(os.path.join(parent_folder_path, 'plugin'))
+
+from flowlauncher import FlowLauncher
+
+
+class HelloWorld(FlowLauncher):
+
+    def query(self, query):
+        return [
+            {
+                "Title": "Hello World, this is where title goes. {}".format(('Your query is: ' + query , query)[query == '']),
+                "SubTitle": "This is where your subtitle goes",
+                "IcoPath": "Images/app.png",
+                "JsonRPCAction": {
+                    "method": "do_something_for_query",
+                    "parameters": [param1, param2]
+                }
+                "ContextData": "ctxData",
+            }
+        ]
+
+    def context_menu(self, data):
+        return [
+            {
+                "Title": "Context menu entry",
+                "SubTitle": "Data: {}".format(data),
+                "IcoPath": "Images/app.ico",
+            }
+        ]
+
+    def do_something_for_query(self, param1, param2):
+        pass
+
+if __name__ == "__main__":
+    HelloWorld()
+
+```
+
+<br/>
+
+### 3. Query entry point 
+**def query(self, query):**
+
+This is the main entry to your plugin and the return block will be a list of the results that your plugin returns, which could be a single or many results.  
+
+### 4. Assigning an action to your results  
+**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.
+
+### 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. 
+
+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.
+
+### 6. Your plugin.json
+
+You will also need to if not yet already, create a plugin.json file that will instruct Flow on how to load your plugin.
+
+This file should be placed in the top level folder.
+
+To revisit what to include in your plugin.json, visit [here](https://flow-launcher.github.io/docs/#/plugin.json)