smsearcy/zeal-feeds

Command line application for adding user contributed docsets to Zeal.

zeal-feeds

---

zeal-feeds is a command line application for adding user contributed docsets to Zeal, as an alternative to looking up the URL of the XML feed and pasting in the Add Feed option.

Table of Contents

• Installation
• Usage
• Acknowledgements
• License

Installation

The recommended way to install zeal-feeds is via pipx, to provide an isolated installation.

$ pipx install zeal-feeds

Alternatively, zeal-feeds can be installed via pip, either for the current user or into the current Python virtual environment.

Warning

This package will install several dependencies into the current environment. Consider using pipx to avoid dependency conflicts.

$ pip install --user zeal-feeds

or

$ pip install zeal-feeds

Usage

To search available feeds, use zeal-feeds search:

$ zeal-feeds search alpine
⠴ Loading index of user contributed docsets
Matching docsets:
Alpinejs (3.7.x/5_2021-12-14)

To install feeds, use zeal-feeds install. The docset name needs to match the name from the search results:

$ zeal-feeds install alpinejs attrs
Using cached index of user contributed docsets
Downloading Alpinejs ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
.   Installing Alpinejs
Downloading attrs ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
.   Installing attrs

If a docset is already installed then it will be skipped.

Acknowledgements

This project was inspired by zeal-user-contrib, but the apparent lack of an npm equivalent of pipx for isolated installations prompted writing a Python version.

This article by Hynek Schlawack for introducing Dash/Zeal.

https://zealusercontributions.vercel.app/ for providing the docset API with XML feeds for Zeal.

Contributing

Please open an issue or pull request on GitHub if you have questions, ideas, or issues.

zeal-feeds uses hatch. Run hatch run lint to run checks (Black, Ruff, and mypy) and hatch run test:pytest to run unit tests.

License

zeal-feeds is distributed under the terms of the MIT license.

zeal-feeds's Issues

Packaging updates

Add CI actions to build/publish package and verify that the right stuff is included in the source distribution (when run locally it picked up my PyCharm settings directory).

MVP

Basic command line to download and install a user contributed docset specified on the command line.

Option to clear/bypass cached index

Currently the docset index is cached for 12 hours, but it's reasonable to think that there might be times when that needs to be cleared or bypassed.

Two possibilities:

1. Add a command to clear the cache, e.g. clean.
2. Add an option for install and search to ignore the cache, e.g. --no-cache or --refresh.

Ensure icons in docset folder

One feature of zeal-user-contrib is that if either icon wasn't created in the .docset folder (because it was missing from the tarball), then the missing icons were created (if they existed) from the icon data in the JSON.

That seems like a worthwhile improvement.