bantya / keypirinha-zealous

Keypirinha plugin for exploring Zeal docs.

Keypirinha Plugin: Zealous

This is Zealous, a plugin for the Keypirinha launcher.

This plugin is developed to facilitate the offline documentation search using the awesome Zeal app.

Zealous demo

Background

Zeal is one of the best offline documentation search tool available today. Its docsets are made available by Dash.

Zeal App for Windows

It provides the ability to install docsets for almost all of the mainstream languages, tools, toolsets and everything that can have its own docset. It can filter the results as per the result type (highlighted above 👆).

Install

There are two ways to install:

1. Using PackageControl:

   • Invoke Keypirinha and type install package.
   • Click enter.
   • Now search for package Keypirinha-Zealous.
   • Again press enter.

2. Manual:

   Download the latest plugin file from here.

   Once the Zealous.keypirinha-package file is downloaded, move it to the InstalledPackage folder located at:

   • Keypirinha\portable\Profile\InstalledPackages in Portable mode
   • Or %APPDATA%\Keypirinha\InstalledPackages in Installed mode (the final path would look like C:\Users\%USERNAME%\AppData\Roaming\Keypirinha\InstalledPackages)

NOTE: You may have to manually restart Keypirinha to see the package activated.

Configuration

1. Open the Zealous config file.

   Zealous configuration menu

2. The main section is necessary if you installed the Zeal to non-default location. You will have to provide the Zeal install path and the docsets path in this case.

3. The result is the count of how many entries to be fetched from the Zeal docsets. Default: 50

4. The wildcard if set to yes enables wildcards to be used to get the refined result set, else the results will be generated using fuzzy search. Default: no

5. Add the entries to the docs section.

• The syntax for the docs entry should be:

  [Docset mnemonic] = [The zeal docset search phrase]
  
  e.g.
  
  php = php
  ld = laravel
  js = javascript
  sql = mysql
  py = python
  

  ℹ The zeal docset search phrase i.e. zeal doc identifier can be discoverd as explained here.

6. Add the entries to the types section.

   Which can be seen as highlighted part in Zeal App image above 👆.

• The syntax for the types entry should be:

  [Type mnemonic] = [The zeal docset types]
  
  e.g.
  
  g = Guide
  h = Helper
  sec = Section
  key = Keyword
  

  ℹ The docset types can be found here.

• There are some quirks. Some dataset entrytype (as Zeal calls it) are not as exact as the specified in here.

  Especially, php along with some other docsets, does not follow the rule. So to make it play even with such docsets, we have to add the supported non-exact result types also.

  e.g.
  
  f = Function,func
  m = Method,clm
  c = Class,cl
  p = Property,instp
  t = Type,tdef
  mc = Macro,macro
  

• All the fields in the above syntax are REQUIRED.

Zealous configuration files

Usage

Invoke Keypirinha and put the terms as follows.

• The syntax for the usage should be:

  [Docset mnemonic] [Result type]? [Search term]
  
  e.g.
  
  php explode  -> searches 'explode' in PHP docset
  ld g auth  -> searches 'auth' of 'Guide' type in Laravel docset
  js key ...obj  -> searches '...obj' of 'Keyword' type in Javascipt docset
  

Zealous simple usage.

• Though the usage of [Result type] is optional, using it filters the results only to that type.

Zealous advanced usage with type provided.

When wildcard is set to yes

[Docset mnemonic] [Result type]? [*?Search term*?]

e.g.

php expl*  -> searches entries starting with 'expl' in PHP docset
php *de  -> searches entries ending with 'de' in PHP docset
php *pl*  -> searches entries containing 'pl' anywhere in PHP docset

Change Log

v1.1.0

• Added wildcard functionality.
• Updated config file.
• Bumped version to v1.1.0

v1.0.2

• Corrected package-name typo.

v1.0.1

• Added PackageControl section in README.
• Updated config file.

v1.0.0

• Bumped version to v1.0.0
• Full working release.
• Added advanced searching ability.
• Updated the README.

v0.0.2 (Unreleased)

• Added docset db search.
• Added simple searching.

v0.0.1 (Unreleased)

• First working draft

License

This package is distributed under the terms of the MIT license.

Credits

Do some work and add your name here!

Contribute

This is how to contribute:

1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
2. Fork this repository on GitHub to start making your changes to the dev branch.
3. Send a pull request.
4. Add yourself to the Contributors section below (or create it if needed)!

And what?

Thanks to all.

keypirinha-zealous's Issues

plistlib fail on some files and zealous breaks

If you add docset feeds from third party maintainers, like from example
https://github.com/hashhar/dash-contrib-docset-feeds/blob/master/Clang.xml
It has Info.plist file in single line, no multiline, I guess that makes plistlib to fail loading it, I really don't know.

However, Zeal will import it correctly, but plistlib in Zealous fails to load Info.plist, and reading the next docsets in the for loop breaks, so it won't work with this plugin.

So one way to avoid that is using an exception catcher, as in the correction I did in order to make it work.

def on_start(self):
        self._load_settings()
        self._gather_docs()
        self._gather_types()

        self.package_path = self.get_package_cache_path(True)
        self.docsets_json = os.path.join(self.package_path, 'docsets.json')

        default_docset_path = kp.package_cache_dir().split('Keypirinha\\Packages')[0] + 'Zeal\\Zeal\\docsets'
        self.docsets_path = self.settings.get_stripped('docset_path', self.SECTION_MAIN, default_docset_path)

        json_data = self._read_json()

        for key in self.docs:
            docset = self.settings.get_stripped(key, self.SECTION_DOCS)
            if docset not in json_data.keys():
                for folder_name in os.listdir(self.docsets_path):
                    plist_path = os.path.join(self.docsets_path, folder_name, self.PLIST_FILE)
                    if os.path.isfile(plist_path):
                        with open(plist_path, 'rb') as fp:
                            try:
                                pl = plistlib.load(fp)
                                if docset == pl["DocSetPlatformFamily"]:
                                    self.icon_path = os.path.join(self.docsets_path, folder_name)

                                    self._save_docsets(docset, folder_name.split('.docset')[0])
                                    self._copy_icon(docset)
                            except Exception :
                                self.info('Error reading plist file')

I hope you can fix it, as this https://github.com/hashhar/dash-contrib-docset-feeds is awesome.

Config Question

Hey Bantya, I am unsure what I'm doing wrong...I've got the necessary fields populated on the right hand side for the writable config file. Thanks!