Keen-Docs holds all of the Documentation for Keen IO.
It is a submodule of Keen-Web.

Prerequisites for updating Keen Docs: 
o You have the Keen environment running locally. See Keen-Web and Keen-Service READMEs.
o Install Sphinx.

Steps to Install Sphinx:
1. [michelle] ~ $ sudo easy_install -U Sphinx

	Note: If you get the error "ImportError: Entry point ('console_scripts', 'easy_install') not found", install Distribute:
	[michelle] ~ $ curl -O http://python-distribute.org/distribute_setup.py
	[michelle] ~ $ sudo python distribute_setup.py

Keen Docs Development Process:
1. Navigate to Keen-Web and enter your virtual environment.
	[michelle] ~/Dev/Keen-Web $ v mykeenweb
	(mykeenweb)[michelle] ~/Dev/Keen-Web $

2. Check status of your local environment. Download the latest Keen-Web from master if needed.
	(mykeenweb)[michelle] ~/Dev/Keen-Web $ git status
	# On branch master
	nothing to commit, working directory clean
	(mykeenweb)[michelle] ~/Dev/Keen-Web $ git pull

3. You must also download a submodule update of Keen-Web, since Keen-Docs is a submodule of Keen-Docs.
	(mykeenweb)[michelle] ~/Dev/Keen-Web $ git submodule update

4. Checkout the master branch of Keen-Docs
	(mykeenweb)[michelle] ~/Dev/Keen-Web/app/Keen-Docs $ git checkout master

5. Use TextMate to modify .rst files in Sphinx language and save your changes. You should only modify .rst and .txt files in the "source" folder. Never modify html files for the docs; those are built by Sphinx.
	(mykeenweb)[michelle] ~/Dev/Keen-Web/app/Keen-Docs $ mate source

6. Do a git status in Keen-Docs to take a look at the rst changes you've made to make sure everything looks ok.
	This step is FYI only.

	(mykeenweb)[michelle] ~/Dev/Keen-Web/app/Keen-Docs $ git status
	# On branch master
	# Changes not staged for commit:
	#   (use "git add <file>..." to update what will be committed)
	#   (use "git checkout -- <file>..." to discard changes in working directory)
	#
	#	modified:   source/index.rst
	#
	no changes added to commit (use "git add" and/or "git commit -a")

7. Now you need to run a Sphinx build process to turn your rst files into HTML.
	(mykeenweb)[michelle] ~/Dev/Keen-Web/app/Keen-Docs $ make keenhtml

8. Review the list of warnings that are displayed. Sphinx will call out broken references, links, and ill formatting for tables and such. Make changes and re-run make keenhtml until the errors and warnings are resolved.

9. Preview and test your changes in your local environment. Typically, it's http://localhost:5000. Make changes and re-run make keenhtml until all is well.

10. Now do a git status in Keen-Docs to take a look at your changes. You'll see rst changes as well as html changes. 

	(mykeenweb)[michelle] ~/Dev/Keen-Web/app/Keen-Docs $ git status
	# On branch master
	# Changes not staged for commit:
	#   (use "git add <file>..." to update what will be committed)
	#   (use "git checkout -- <file>..." to discard changes in working directory)
	#
	#	modified:   source/index.rst
	#	modified:   build/keenhtml/_sources/index.txt
	#	modified:   build/keenhtml/searchindex.js
	#
	no changes added to commit (use "git add" and/or "git commit -a")

	Note: searchindex.js is updated pretty much every time your make a change anywhere in sphinx docs.

11. Commit your changes to Keen-Docs.
	
	(mykeenweb)[michelle] ~/Dev/Keen-Web/app/Keen-Docs $ git commit -a -m 'docs: Keen IO and remove meta-analysis page'
	[master 7b9e0cf] docs: Keen IO and remove meta-analysis page
 	3 files changed, 7 insertions(+), 26 deletions(-)
 	rewrite build/keenhtml/objects.inv (88%)
 	rewrite build/keenhtml/searchindex.js (100%)
 	delete mode 100644 source/data-analysis/meta-analysis.rst
	
	(mykeenweb)[michelle] ~/Dev/Keen-Web/app/Keen-Docs $ git status
	# On branch master
	# Your branch is ahead of 'origin/master' by 1 commit.
	#
	nothing to commit, working directory clean

12. Do a git pull to see if there are any new updates on Keen Docs. 
	
	Resolve or discard conflicts, rebuild docs, and re-commit until git pull says it is up to date.

	(mykeenweb)[michelle] ~/Dev/Keen-Web/app/Keen-Docs $ git pull
	Already up-to-date.

13. Push the changes to Keen-Docs master
	(mykeenweb)[michelle] ~/Dev/Keen-Web/app/KEen-Docs $ git push origin master

14. Navigate to Keen-Web and check status. You should have master branch checked out.
	
	(mykeenweb)[michelle] ~/Dev/Keen-Web $ git status
	# On branch master
	# Changes not staged for commit:
	#   (use "git add <file>..." to update what will be committed)
	#   (use "git checkout -- <file>..." to discard changes in working directory)
	#
	#	modified:   app/Keen-Docs (new commits)
	#
	no changes added to commit (use "git add" and/or "git commit -a")

15. Commit these changes to Keen-Web master.

	(mykeenweb)[michelle] ~/Dev/Keen-Web $ git commit -a -m 'docs: Keen IO and remove meta-analysis page'
	[master 524d3ab] merged docs udpates
 	1 file changed, 1 insertion(+), 1 deletion(-)

16. Pull the latest Keen-Web master to check for conflicts. 

	(mykeenweb)[michelle] ~/Dev/Keen-Web $ git pull

	Work out the conflicts until git pull says Already up-to-date.

17. Push the Keen docs changes to Keen Web master.

	(mykeenweb)[michelle] ~/Dev/Keen-Web $ git push origin master

	(mykeenweb)[michelle] ~/Dev/Keen-Web $ git push origin master
	Counting objects: 13, done.
	Delta compression using up to 4 threads.
	Compressing objects: 100% (9/9), done.
	Writing objects: 100% (9/9), 961 bytes, done.
	Total 9 (delta 6), reused 0 (delta 0)
	To https://github.com/keenlabs/Keen-Web.git
   		b386b23..dae795c  master -> master


Now you have successfully deployed all your changes to the repository!!

Here's how to deploy them to the web.

1. Deploy the new Keen-web code to staging, type this in HipChat:

	@robot keen deploy web to staging
	
2. Go to staging.keen.io to checkout the changes

3. If successful, deploy web to prod by typing this in HipChat:

	@robot keen deploy web to prod