API reference manual for offline documentation

[manad777]

I'm working on my first Node project while traveling and internet access is not constant. Yesterday I got stuck due to lack of doc while offline. I'm in a cafe right now downloading as much doc as I can for everything I imagine needing (if you don't know about it, devdocs.io is a huge help here).

Bluebird's doc is hard to obtain, because it's scattered across multiple HTML pages. I'll be using a web scraper, but this is a lot of effort for the average person. It would be better if Bluebird had a PDF or single HTML document containing the entire API reference, in addition to the current structure.

Thoughts?

[benjamingr]

You can download the website as a zip folder (or check it out) from the gh-pages branch: https://github.com/petkaantonov/bluebird/tree/gh-pages

Then extract that and the pages will work locally.

[petkaantonov]

I guess we could make it work offline easily with ServiceWorker?

[benjamingr]

@petkaantonov the user wants to download it to their computer - not have an offline version of the site itself that syncs through the browser.

[petkaantonov]

ServiceWorker downloads the site to your computer, it works completely offline

[benjamingr]

The goal is not to make bluebirdjs.com it's to make the reference available to the user - cloning the repo also downloads the site to your computer and works completely offline and doesn't require HTML changes or different browser support and works even if the user has an older browser.

[bergus]

I'd agree that a ServiceWorker is overkill, and a download of the gh-pages zip should be enough. Maybe even link that from the website.

However OP also mentions another issue:

Bluebird's doc is scattered across multiple HTML pages.

Could you make Jekyll to render them to a single-page version as well? Like the late API.md?

[manad777]

@benjamingr , thanks for the tip. I just tried it and it works (as long as you open api-reference.html rather than index.html. Also the "Return to API reference" links are broken once an entry is open, but you can use the browser's Back button to return to the API list.)

I'm OK with this being the official way of having an offline reference, but the average person browsing the site has no way of knowing any of this. Can we put your instructions to download bluebird-gh-pages on the website under a "Download API reference" link? I know this isn't a common request, and I know the average dev should know how to scrape a website, I just think it's better when libraries have a downloadable reference document on their website.

[petkaantonov]

@manad777 I have created http://bluebirdjs.com/docs/download-api-reference.html. PRs for content are welcome