search

AlaSQL / alasql

AlaSQL.js - JavaScript SQL database for browser and Node.js. Handles both traditional relational tables and nested JSON data (NoSQL). Export, store, and import data from localStorage, IndexedDB, or Excel.
http://alasql.org
MIT License
7.02k stars 655 forks source link

Generating documentation for offline read #834

Open zcattacz opened 7 years ago

zcattacz commented 7 years ago

I found a easier way to download the project wiki for offline use. Maybe you will find it interesting too.

https://github.com/zcattacz/alasql_wiki

It's quite simple. Since github is blocked by firewall here. It always got me frustrated working with repo from github in local git. So I forked the .wiki repo on github, added conf.py and index.rst from (https://github.com/ericholscher/sphinx-markdown-test , also see http://blog.readthedocs.com/adding-markdown-support/ ) and created a project on ReadTheDoc with the resulting fork.

The only reason the wiki repo has to be forked is because, I can't find a way to insert a off repo .rst index. If agershun doesn't mind creating a RST version (wiki edit mod: "reStructured Text") of the wiki home page as proper TOC for the offline document. The generated offline epub/pdf can be better structured. ( conf.py can be specified in RTD advanced settings, as an off repo file link e.g. a raw gist link. then to generate the offline doc, there will be no need to fork the wiki repo )

Just a suggestion. Thanks for your great work .

mathiasrw commented 7 years ago

Hi @zcattacz

We are looking into making the documentation more structured - moving it away from the wiki. Your idea is neat. We are already woking on a setup using mkdocs. We are having a test demo site just to try out things. I have made a page that concats all wiki posts so you can download them offline for the moment:

http://alasql.surge.sh/wiki/_/

zcattacz commented 7 years ago

Hi @mathiasrw, that looks a good start. RTD supports mkdoc too http://docs.readthedocs.io/en/latest/builds.html#mkdocs . either way the index has to be maintained in the repository.

I prefer epub over pdf on mobile device. their text can be reflowed. layout more adaptive, unlike pdf which has to be zoomed in and out. If you can provide epub download, i can remove my test project on RTD.

Since RTD's web hook on github rebuilds the 'latest' version of documentation after each commit. the 'latest' version of document on rtd is always automatically up to date. that's neat.