Ably Documentation Overview
Ably is a hugely scalable, superfast and secure hosted realtime messaging service for web-enabled devices.
The Ably documentation was intentionally created as a public repository using a simple text based markup language so that:
- It can be maintained by Ably staff and developers.
- 3rd parties can fork the repository, and submit pull requests to improve the documentation. We welcome the community's suggestions and input.
- This documentation is later merged upstream to the Ably primary website documentation with each website release.
Viewing the documentation
The static site generated from this documentation repository is hosted at http://docs.ably.io and deployed automatically when the
master branch is updated. We frequently publish updates from this repository so is typically more up to date than the official Ably API documentation.
The official complete Ably documentation that incoporates all the documentation in this repository can be found at https://www.ably.io/documentation
Forking and running locally
- Fork the repository at https://github.com/ably/docs
- Clone a local version of your forked repo
git clone https://github.com/[you]/docsand
- Checkout the master branch:
git checkout master
- Create your feature or fix branch and check it out:
git checkout -b [your-branch]
bundle installto install the necessary gems
- Create a jsbin config file:
cp config/jsbin_config.example.yaml config/jsbin_config.yaml
At this point you can either run the repo directly on your machine or via Docker.
If you have Ruby and are comfortable working in a Ruby environment as follows:
nanoc compileto generate the site for the first time
nanoc view -p 4000to start up a web server at http://localhost:4000
bundle exec guardto watch for changes and rebuild the site automatically. This is normally run in conjunction with the
.nanoc view -p 4000command so that you can see changes immediately
If you would prefer to use Docker, then you can set up the env as follows:
./docker-run buildto build the initial Docker image
./docker-run compileto compile the HTML for the static site (this is a once off command)
./docker-run serverto start up a web server at http://localhost:4000
./docker-run guardto watch for changes and rebuild the site automatically. This is normally run in conjunction with the
./docker-run servercommand so that you can see changes immediately
Running on Heroku
This repo will automatically run on Heroku, but relies on the following buildpacks (see https://github.com/ably-forks/heroku-buildpack-nanoc):
$ heroku buildpacks === ably-docs Buildpack URLs 1. https://github.com/heroku/heroku-buildpack-ruby 2. https://github.com/ably-forks/heroku-buildpack-nanoc 3. https://github.com/heroku/heroku-buildpack-static
- Assuming you have followed the steps above, prior to making a PR, make your changes locally and they should be visible within seconds in the browser following a refresh (if using the
guardcommand, else a manual
compileis required). If the changes are not visible, check your console where
guardis running for errors.
- Commit your changes, push your branch and send us a pull request
- All pull requests will automatically launch a static review site that will be linked to at the bottom of the PR
Help and contact
If you have any questions or suggestions, please get in touch with us at Ably