search

quicksilver / manual

Quicksilver Manual
3 stars 2 forks source link

Automated plugin documentation #1

Closed joshringer closed 6 years ago

joshringer commented 6 years ago

Opening a ticket to track progress. Committing to my fork here for now: joshringer/manual

So far, I'm scraping all plugin-looking (ends in -qsplugin) repos from the quicksilver org, copying across any Documentation.md type files into the docs tree and adding a toc entry to mkdocs.yml

Couple of things still to figure out right away:

  1. Plugin name. Guessing from the repo string right now, feel like there's probably a better string hiding somewhere?
  2. Old plugins? There's a LOT. I think I'm sort of avoiding most of the outdated ones by only looking for the newer .md file, but unsure if there are still some discontinued I'm including unnecessarily. Can probably work in a blacklist fairly easily...
skurfer commented 6 years ago

Plugin name. Guessing from the repo string right now, feel like there's probably a better string hiding somewhere?

The Info.plist should have that. We probably want CFBundleDisplayName. There’s a Python library for parsing property lists.

Old plugins?

The best answer for this might also be in Info.plist. The update system uses information under QSRequirements to decide what you can install from a given machine. Maybe we could configure the script to only consider plug-ins that will work with the current version of QS (from https://qs0.qsapp.com/plugins/check.php) and the last supported version of the OS (which we’d probably have to define manually)?

Thanks for starting on this!

skurfer commented 6 years ago

Actually, we don’t need to reinvent the wheel here. We can just query the update system for a list of “current” plug-ins.

Something like https://qs0.qsapp.com/plugins/info.php?qsversion=16420

(It uses the decimal version of the build number, which is usually hex)

I’m not sure if we can pass OS version as an argument, or if we need to fake the user-agent for that part to work.

The tricky part would be figuring out which GitHub repo corresponds to each entry in that list. Maybe we just need to get them all like you do now and filter them.

joshringer commented 6 years ago

The Info.plist should have that. We probably want CFBundleDisplayName. There’s a Python library for parsing property lists.

Yep, looking like this + potentially backup CFBundleName, though I suspect the out-of-date plugins in most cases to be the non-conforming.

The tricky part would be figuring out which GitHub repo corresponds to each entry in that list. Maybe we just need to get them all like you do now and filter them.

I can't see an obviously safe way to match them beyond fetching all the repos and matching against CFBundleIdentifier. Could save a map of the results to avoid searching until a new one appears. Aside from minor space concerns, it's not too big a deal to just pull them all right now..

joshringer commented 6 years ago

Hmm.. So I've been poking around in the info.php code looking into the best way to pull out what I want. The main issue is obviously at the moment it is set out to query for one specific qs/os version, and what would be good here is a range. I could expand querying support to the interface I guess, just trying to decide if it's worth the trouble.

I'm also getting tripped up by template strings in the source Info.plist files, which is annoying.

joshringer commented 6 years ago

Having said that, I notice the info.php output also includes documentation. Question: The extendedDescription field there is built from the Documentation.md files right? Is there ever a case where we might want extra docs from the plugin repositories other than what's included in that field? If so, can potentially save a lot of effort by just scraping direct from there. Looks like mkdocs will allow raw html. Thoughts?

skurfer commented 6 years ago

Back from spring break…

The extendedDescription field there is built from the Documentation.md files right?

Yes.

Is there ever a case where we might want extra docs from the plugin repositories other than what's included in that field?

Not currently, and I would discourage ever having documentation that didn’t appear in that field since that’s what you can get to in the app.

If so, can potentially save a lot of effort by just scraping direct from there. Looks like mkdocs will allow raw html.

Yeah, that might work. You’d just have to watch out for the ones where Xcode touched the file after bltrversion generated the docs. It tends to convert everything to HTML entities.

joshringer commented 6 years ago

Cool. Found a module that seems to do a good job of sending html back to markdown.

Just need to do a bit of work on filtering with OS versions and I think it'll be good for a first pass.