Create Documentation Docset compatible w/ Dash for offline access

[enchev]

From @sfeather on July 11, 2015 23:37

See https://kapeli.com/docsets for reference

Copied from original issue: NativeScript/NativeScript#420

[enchev]

From @moll on July 29, 2015 12:11

:+1:

[enchev]

From @sfeather on July 30, 2015 1:15

@valentinstoychev are ya'll using anything to auto-generate the current docs from source/etc at the moment? Thinking this would be best if automated, and easier to implement that automation before the framework grows too large.

[enchev]

From @valentinstoychev on July 30, 2015 10:37

@sfeather Yes, we have the documentation in markdown format here - https://github.com/NativeScript/docs. The we have a build system that is using jekyll to generate the HTML pages. @ErjanGavalji can tell you more details if needed.

[enchev]

From @sfeather on August 2, 2015 20:35

doh! Thanks @valentinstoychev, how I walked right past that and missed the md files I have no idea.

[alg]

Created a simple Ruby script to export ApiReference, Core concepts and User Interface sections to Dash docset. Nothing fancy, just modules, classes and guides.

[stephenfeather]

Using ALG's theme (https://github.com/alg/typedoc-dash-theme) works well with the new typedoc additions.

We will need at least the following:

1. Index Page (project info, version docs generated against, urls to important sites, etc)
2. ~~Icon Reference~~
3. Fallback url to the online docs

ed: ~~Once thats done, suggest the docset be auto-generated for each release, contributed to dash (https://github.com/Kapeli/Dash-User-Contributions#contribute-a-new-docset) by the NativeScript project (vs a community member) for authority's sake. This will allow it to be on the list of available docsets when a user installs dash~~

Thank you @alg

[stephenfeather]

So, to move this to a discussion state, @alg where in the repo (or not) would you suggest the index and icon be stored so your script could access it?

I'd be more than happy to create the index page if we can decide where it should live.

[stephenfeather]

Here are two icons to go in NativeScript.docset/

[alg]

Hi gents. The docset is on the list of user-contributed docsets and available for install through the app for quite some time yet. Taking over the updates etc is fine by me. I hope you leave some credits for the work done. :)

There are several things still on my TODO list for the Typedoc theme that I'm hoping to get back to soon. Removing private methods and properties (those with names starting with the underscore) and adding icons are among them. Adding guides and how-to's would be awesome too, but would require an additional script since it's outside the scope of generic Typedoc Dash theme.

As for the icon, I was looking into passing various configuration settings to the theme, and so far the best way is using environment variables. This way, I'll be able to tell where to grab the icon. So far, I was adding this icon manually to the docset.

[stephenfeather]

I have no interest in credit, simply need offline docs in a workflow I've been using for a while. If you have already submitted it, then by all means keep at it.

Env variables make sense, i hadn't really liked putting the icons into the code repo

[alg]

Same here. I don't mind you guys taking over releasing the doc updates after the {N} releases (which is logical). That would actually be nice if you included it in your release cycle.

I'll have a look at including icon setting into the theme and let you know.

[alg]

Here's the tiny repo with all one need to generate the docset: https://github.com/alg/nativescript-dash-docset

[ErjanGavalji]

@alg, your contribution is awesome and really, really appreciated, man!

I'd prefer that the core team cooperates with you on having the release automated instead of having it taken over. We will try arranging resources if you don't have them.

This will be especially useful for the community as it will start creating a guideline of integrating community-maintained projects with the release cycle of the core team.

Are you on for that effort?

Cheers, Erjan

[alg]

@ErjanGavalji, I'm totally fine with either way, mate. How close of integration are you thinking of? Currently it's just "whenever I notice you guys released a new version" kind of integration. I can imagine starting a tiny web server to get hook call from github (or anywhere else) that triggers the docset rebuilding and submission to Dash repo. I know it doesn't have to be perfectly in sync with releases though.

[ErjanGavalji]

@alg (sorry for not being able to write the reply that was in my mind since Friday earlier), that's exactly what I meant: plugging in a webhook so that your webserver knows it. The more automated it is, the better for the community. Still, it is no rush, you are right we don't need a perfect sync (at least for the time being).

[olostan]

Do anyone have any downloadable resource with offline help of {N}?

[ErjanGavalji]

@olostan, we don't distribute the docs, however we can produce a package and publish it to the releases section. How about that?

[ErjanGavalji]

@olostan, however, won't the dashset @alg created work better?

[olostan]

@ErjanGavalji I've used @alg repository to generate docset. But it would be really useful to have a possibility to download already generated docset. It could be not only Dash - any kind of offline documentation would be valuable (before seeing @alg solution, I even tried to mirror {N} web site locally for offline viewing :))

[alg]

@olostan Dash docset is officially available in Dash User Contributed Docsets. You can install it and use offline. No need to build from repo.

[olostan]

@alg thnx! Removed self-made, added from DUCD. It would be good to mention somewhere at official doc that Dash docset if available.

[nraboy]

I would love to see this maintained and a part of the official Dash docset.