0.0.2

README.rst

@@ -36,6 +36,7 @@ The Alfred Workflow: Full Text Search Anything
     :local:
     :depth: 1
 
+
 .. _introduction:
 
 Introduction
@@ -101,22 +102,22 @@ Search Setting (content of ``movie-setting.json``):
         "title_field": "{title} ({genres})", // title on Alfred drop down menu
         "subtitle_field": "description", // subtitle on Alfred drop down menu
         "arg_field": "movie_id", // argument for other workflow component
-        "autocomplete_field": "{movie_id} - {title}", // tab auto complete behavior
+        "autocomplete_field": "{title}", // tab auto complete behavior
         "icon_field": "/Users/<username>/.alfred-fts/movie-icon.png"
     }
 
 
-Note: ``fts.anything`` support comment in json.
+Note: ``fts.anything`` support comments in json.
 
 
 .. _install:
 
-Install
+1. Install ``alfred-fts``
 ------------------------------------------------------------------------------
 Go to `Release <https://github.com/MacHu-GWU/afwf_fts_anything-project/releases>`_, download the latest ``Full-Text-Search-Anything.alfredworkflow``. And double click to install to alfred.
 
 
-Usage Guide
+2. Configure Alfred Workflow Settings
 ------------------------------------------------------------------------------
 
 1. Create an ``.alfred-fts`` directory in your ``${HOME}`` dir (``/Users/<username>``). This is where you put your dataset file and setting file.
@@ -131,7 +132,7 @@ Usage Guide
 .. image:: https://user-images.githubusercontent.com/6800411/50622685-41710d00-0edd-11e9-9ac9-c904ed0bfd4f.png
 
 
-FTS Anything Setting File
+3. Configure Dataset and Setting File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is a dictonary with 6 fields:
@@ -170,7 +171,7 @@ It is a dictonary with 6 fields:
         "title_field": "{title} ({genres})", // title on Alfred drop down menu
         "subtitle_field": "description", // subtitle on Alfred drop down menu
         "arg_field": "movie_id", // argument for other workflow component
-        "autocomplete_field": "{movie_id} - {title}", // tab auto complete behavior
+        "autocomplete_field": "{title}", // tab auto complete behavior
         "icon_field": "/Users/<username>/.alfred-fts/movie-icon.png"
     }
 
@@ -218,3 +219,33 @@ FAQ
 
 - Q: Why it still returns old data after I updated the dataset?
 - A: Just delete the ``${HOME}/.alfred-fts/<dataname>-whoosh_index`` directory.
+
+
+Projects based on ``alfred-fts``
+------------------------------------------------------------------------------
+
+- search AWS CloudFormation Resource and Property Reference, quickly jump to Official AWS CloudFormation Resource and Property Document: https://github.com/MacHu-GWU/alfred-cloudformation-resource-property-ref
+- search Terraform AWS Resource Reference, quickly jump to Official Terraform AWS Resource Document: https://github.com/MacHu-GWU/alfred-terraform-resource-property-ref
+
+
+Developer Guide
+------------------------------------------------------------------------------
+
+
+How to Develop this library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First you need to prepare the data file ``${HOME}/.alfred-tfs/movie.json`` and ``${HOME}/.alfred-tfs/movie-setting.json``.
+
+Then use ``tests/test_handlers.py`` to implement test cases for input argument, returned items.
+
+
+How to Release new version of Alfred Workflow using this library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Run ``build.sh``, Workflow artifacts will be packed into ``afwf_fts_anything-project/workflow/``
+2. Create a Empty Workflows.
+3. Right Click on this Workflow, Click "Open in Finder".
+4. Copy all content from workflow into the folder.
+5. Right Click on this Workflow, Click "Export", it will be export to ``Full Text Search Anything.alfredworkflow`` file.
+6. Issue a new GitHub Release, and upload the ``Full Text Search Anything.alfredworkflow``.

afwf_fts_anything/__init__.py

@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
 
 """
-Package Description.
+Full text search workflow for Alfred.
 """
 
-__version__ = "0.0.1"
-__short_description__ = "Package short description."
+__version__ = "0.0.2"
+__short_description__ = "Full text search workflow for Alfred."
 __license__ = "MIT"
 __author__ = "Sanhe Hu"
 __author_email__ = "[email protected]"

afwf_fts_anything/dataset.py

@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
 
+"""
+This module is an integration layer put full-text-search-settings, dataset,
+whoosh schema all together.
+"""
+
 import attr
 import shutil
 from attrs_mate import AttrsClass

afwf_fts_anything/fts_setting.py

@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
 
+"""
+This module implements the abstraction of the dataset settings, and convert the
+settings towhoosh.fields.SchemaClass.
+"""
+
 import six
 import attr
 from collections import OrderedDict
@@ -12,6 +17,19 @@
 @attr.s
 class ColumnSetting(AttrsClass):
     """
+    Per Column Setting.
+
+    :param type_is_store: if True, the value is only stored but not indexed for
+        search. Usually it can be used to dynamically construct value for argument
+        (the action when you press enter), or for auto complete (the action
+        when you press tab)
+    :param type_is_ngram: if True, the value is index using ngram. It matches
+        any character shorter than N characters.
+        https://whoosh.readthedocs.io/en/latest/ngrams.html.
+    :param type_is_phrase: if True, the value is indexed using phrase. Only
+        case insensitive phrase will be matched.
+    :param type_is_keyword: if True, the value is indexed using keyword. The
+        keyword has to be exactly matched.
     :param ngram_minsize: minimal number of character to match., default 2.
     :param ngram_maxsize: maximum number of character to match., default 10.
     :param keyword_lowercase: for keyword type field, is the match case sensitive?
@@ -46,15 +64,15 @@ class Setting(AttrsClass):
     """
     Defines how you want to index your dataset
 
-    :param title_field: which field is used as ``WorkflowItem.title``.
+    :param title_field: which field is used as ``WorkflowItem.title``. It displays
+        as the big title in alfred drop down menu.
     :param subtitle_field: which field is used as ``WorkflowItem.subtitle``.
     :param arg_field: which field is used as ``WorkflowItem.arg``.
     :param autocomplete_field: which field is used as ``WorkflowItem.autocomplete``.
     :param icon_field: which field is used as ``WorkflowItem.icon``.
 
     :param skip_post_init: implementation reserved attribute.
     :param _searchable_columns_cache: implementation reserved attribute.
-
     """
     columns = attr.ib(
         factory=list, converter=lambda columns: [
@@ -97,6 +115,10 @@ def keyword_columns(self):
 
     @property
     def searchable_columns(self):
+        """
+
+        :return:
+        """
         if self._searchable_columns_cache is None:
             self._searchable_columns_cache = list()
             self._searchable_columns_cache.extend(self.ngram_columns)
@@ -106,11 +128,19 @@ def searchable_columns(self):
 
     @property
     def column_names(self):
+        """
+
+        :rtype: List[str]
+        """
         return [c_setting.name for c_setting in self.columns]
 
     def create_whoosh_schema(self):
         """
-        Dynamically create whoosh schema.
+        Dynamically create whoosh.fields.SchemaClass schema object.
+
+        It defines how you index your dataset.
+
+        :rtype: SchemaClass
         """
         schema_classname = "WhooshSchema"
         schema_classname = str(schema_classname)
@@ -134,13 +164,12 @@ def create_whoosh_schema(self):
                 field = fields.STORED()
             attrs[c_setting.name] = field
         SchemaClass = type(schema_classname, (fields.SchemaClass,), attrs)
-        schema = SchemaClass()
+        schema = SchemaClass() # type: SchemaClass
         return schema
 
     def convert_to_item(self, doc):
         """
-
-        By default into schedule
+        Convert dict data to ``WFItem``
 
         for title, subtitle, arg, autocomplete field:
 
@@ -149,6 +178,10 @@ def convert_to_item(self, doc):
             use that field.
         3. if ``setting.title_field`` is a str, and not in any columns fields,
             it must be Python String Format Template.
+
+        :type doc: dict
+
+        :rtype: WFItem
         """
         # whoosh 所返回的 doc 中并不一定所有项都有, 有的项可能没有, 我们先为这些
         # 没有的项赋值 None

afwf_fts_anything/handlers.py

@@ -1,5 +1,9 @@
 # -*- coding: utf-8 -*-
 
+"""
+This is alfred workflow integration layer.
+"""
+
 from __future__ import unicode_literals
 from .dataset import DataSet
 from .icons import ICON_NOT_FOUND

alfred-readme.txt

@@ -2,4 +2,4 @@
 
 User manual and Document can be found at:
 
-https://github.com/MacHu-GWU/afwf_fts_anything-project
+https://github.com/MacHu-GWU/afwf_fts_anything-project

build.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# -*- coding: utf-8 -*-
+
+if [ -n "${BASH_SOURCE}" ]
+then
+    dir_here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+else
+    dir_here="$( cd "$(dirname "$0")" ; pwd -P )"
+fi
+dir_workflow="${dir_here}/workflow"
+rm -r ${dir_workflow}
+mkdir ${dir_workflow}
+pip2.7 install Alfred-Workflow --target="${dir_workflow}"
+pip2.7 install . --target="${dir_workflow}"/lib
+cp ${dir_here}/main.py "${dir_workflow}"/main.py

tests/test_dataset.py

@@ -53,8 +53,8 @@ def setup_class(cls):
             "title_field": "{title} ({genres})",
             "subtitle_field": "description",
             "arg_field": "movie_id",
-            "autocomplete_field": "{movie_id} - {title}",
-            "icon_field": Path(ALFRED_FTS, "movie-icon.png").abspath,
+            "autocomplete_field": "{title}",
+            "icon_field": str(Path(ALFRED_FTS, "movie-icon.png").abspath),
         }
         movie_setting = Setting.from_dict(movie_setting_data)
         cls.dataset_name = dataset_name
@@ -68,10 +68,18 @@ def setup_class(cls):
         index_dir = dataset.get_index_dir_path()
         if index_dir.exists():
             shutil.rmtree(index_dir.abspath)
-        json.dump(movie_data, data_file_path.abspath,
-                  indent=4, sort_keys=True, ensure_ascii=False, overwrite=True, verbose=False)
-        json.dump(movie_setting_data, setting_file_path.abspath,
-                  indent=4, sort_keys=True, ensure_ascii=False, overwrite=True, verbose=False)
+        json.dump(
+            movie_data,
+            data_file_path.abspath,
+            indent=4, sort_keys=True, ensure_ascii=False, overwrite=True,
+            verbose=False
+        )
+        json.dump(
+            movie_setting_data,
+            setting_file_path.abspath,
+            indent=4, sort_keys=True, ensure_ascii=False, overwrite=True,
+            verbose=False
+        )
 
     def test_search(self):
         dataset = DataSet(