From 447b7003152b79b7b4615fa26b2821e5b0088ca5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Samy=20Pess=C3=A9?= Date: Thu, 17 Mar 2016 11:30:06 +0100 Subject: [PATCH] Add gitbook documentation --- .gitignore | 4 +++- README.md | 2 +- book.js | 24 ++++++++++++++++++++++++ docs/README.md | 28 +++++++++++++++++++++------- docs/SUMMARY.md | 17 +++++++++++++++++ docs/assets.md | 14 ++++++++------ docs/deploy.md | 6 +++++- docs/github.md | 20 +++++++++++++++++--- schema.png => docs/schema.png | Bin 9 files changed, 96 insertions(+), 19 deletions(-) create mode 100644 book.js create mode 100644 docs/SUMMARY.md rename schema.png => docs/schema.png (100%) diff --git a/.gitignore b/.gitignore index cf60a409..c9f8187e 100644 --- a/.gitignore +++ b/.gitignore @@ -26,4 +26,6 @@ build/Release # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git node_modules -.env \ No newline at end of file +.env + +docs/_book/ diff --git a/README.md b/README.md index 152f6e29..67aa4f85 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Nuts is a simple (and smart) application to serve desktop-application releases. -![Schema](./schema.png) +![Schema](./docs/schema.png) It uses GitHub as a backend to store assets, and it can easily be deployed to Heroku as a stateless service. It supports GitHub private repositories (useful to store releases of a closed-source application available on GitHub). diff --git a/book.js b/book.js new file mode 100644 index 00000000..32d867b9 --- /dev/null +++ b/book.js @@ -0,0 +1,24 @@ +var pkg = require('./package.json'); + +module.exports = { + // Documentation for Nuts is stored under "docs" + root: './docs', + title: 'Nuts Documentation', + + // Enforce use of GitBook v3 + gitbook: '>=3.0.0-pre.0', + + // Use the "official" theme + plugins: ['theme-official', 'sitemap'], + theme: 'official', + + variables: { + version: pkg.version + }, + + pluginsConfig: { + sitemap: { + hostname: 'https://nuts.gitbook.com' + } + } +}; diff --git a/docs/README.md b/docs/README.md index 6fd75902..d1bae5e7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,19 +1,33 @@ # Nuts Documentation -Please make sure that you use the documents that match your Nuts version. +Nuts is a simple (and smart) application to serve desktop-application releases. + +It uses GitHub as a backend to store assets, and it can easily be deployed to Heroku as a stateless service. GitHub private repositories are supported (useful to store releases of a closed-source application available on GitHub). + +![Schema](./schema.png) + +Please make sure that you use the documentation that match your Nuts version (Latest version is **{{ book.version }}**). ### FAQ There are questions that are asked quite often, [check this out before creating an issue](faq.md). +### Help and Support + +We're always happy to help out with any questions you might have. You can ask a question or signal an issue on [GitHub](https://github.com/GitbookIO/nuts/issues). + ### Guides -- [Deploy it!](deploy.md) -- [Upload assets](assets.md) -- [Setup GitHub webhook](github.md) -- [OS X Auto-Updater](update-osx.md) -- [Windows Auto-Updater](update-windows.md) +We've created a few guides to help you getting started: + +- [Deploy Nuts](deploy.md) +- [Upload release's assets](assets.md) +- [Setup GitHub integration](github.md) +- [Setup OS X Auto-Updater](update-osx.md) +- [Setup Windows Auto-Updater](update-windows.md) - [Debug API](api.md) -- [Use it as a node module](module.md) +- [Use it as a Node.js middleware](module.md) + +---- Using Nuts for your application? [Add it to the list](using-it.md). diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 00000000..ad3f862e --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,17 @@ +# Summary + +- [F.A.Q](faq.md) + +--- + +- [Deploy Nuts](deploy.md) +- [Upload Releases](assets.md) +- [Setup GitHub webhook](github.md) +- [Mac / OS X Auto-Updater](update-osx.md) +- [Windows Auto-Updater](update-windows.md) + +--- + +- [Debug API](api.md) +- [Node.js Middleware](module.md) + diff --git a/docs/assets.md b/docs/assets.md index fff7a892..dd8eca74 100644 --- a/docs/assets.md +++ b/docs/assets.md @@ -1,12 +1,14 @@ -# Assets for releases +# Upload assets for releases -Nuts uses GitHub releases and assets to serve the right file to the right user. +Nuts uses GitHub Releases and assets to serve the right file to the right user. -### Filename +See GitHub guides: [About Releases](https://help.github.com/articles/about-releases/) & [Creating Releases](https://help.github.com/articles/creating-releases/). -It uses some filename/extension conventions to serve the correct asset to a specific request: +### Naming -Platform will be detected from the filename: +Nuts uses some filename/extension conventions to serve the correct asset to a specific request: + +The platform/OS will be detected from the filename: - Windows: filename should contain `win` - Mac/OS X: filename should contain `mac` or `osx` @@ -23,7 +25,7 @@ Filetype and usage will be detected from the extension: | Linux | `.deb`, `.rpm`, `.zip` | -## Example +### Example Here is a list of files in one of the latest release of our [GitBook Editor](https://www.gitbook.com/editor): diff --git a/docs/deploy.md b/docs/deploy.md index d88d1f70..da151a56 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -1,13 +1,17 @@ # Deployment -Nuts can be easily be deployed to a state-less server or PaaS. +Nuts can be easily be deployed to a state-less server or PaaS. It only uses the disk as a cache for assets. ### On Heroku: +Heroku is the perfect solution to host a Nuts instance. + [![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy) ### With docker +Nuts can also be run as a Docker container: + ``` docker run -it -p 80:80 -e GITHUB_REPO=username/repo gitbook/nuts ``` diff --git a/docs/github.md b/docs/github.md index b5938bde..f9b14319 100644 --- a/docs/github.md +++ b/docs/github.md @@ -1,5 +1,19 @@ -# GitHub Setup +# GitHub Integration -Add `http://download.myapp.com/refresh` as a GitHub webhook to refresh versions cache everytime you update a release on GitHub. +By default Nuts fetch releases from GitHub Releases; but sicne Nuts is caching informations, there might be a delay before the creation of the release and the release being served to users. -The secret can be configured using `GITHUB_SECRET` (default value is `secret`). +To solve this issue, you can setup a webhook between Nuts and GitHub, to notify your nuts instance each time GitHub Releases are updated (created/removed/updated). + +### Webhook URL + +Add a [GitHub Webhook](https://help.github.com/articles/about-webhooks/) with the url: + +``` +http://download.myapp.com/refresh` +``` + +It'll refresh versions cache everytime you update a release on GitHub. + +### Secret + +The GitHub Webhook secret can be configured as a environment variable on Nuts: `GITHUB_SECRET` (default value is `secret`). diff --git a/schema.png b/docs/schema.png similarity index 100% rename from schema.png rename to docs/schema.png