howToUpdateDocs.txt

The documentation for pybvc is autogenerated and hosted on Github.  This document describes how to update the docs on Github.
1.  You need to have Sphinx installed.  This is the tool that autogenerates the documentation from the comments in the Python code.
2.  You need to have both a branch-of the master branch and a branch-of the gh-pages branch:
       - git checkout master
       - git pull --rebase upstream master
       - git checkout -b master-docs
       - git checkout gh-pages
       - git pull --rebase upstream gh-pages
       - git checkout -b gh-pages-docs
2.  You need to have written comments (in Sphinx format) in the Python source code.
3.  You need to be in the 'master-docs' branch 
       - git checkout master-docs
4.  You need to be at the top directory (it should contain dodoc and publishdoc scripts)
5.  Run:   ./dodoc
    This will run Sphinx and generate new documentation from the comments in the code.  It may ask you if you want to
    replace files in docsForGhPagesBranch, indicate you want to replace (A)ll.
5.  Run:   ./publishdoc
    This will move the generated html documentation files from the master-docs branch to the 'gh-pages-docs' branch
    The gh-pages-docs branch is special in Github and it will generate a web page from the contents of this branch.
    When the script is done you will be left in the gh-pages-docs branch.  Do not move out of the branch yet.
6.  Run:  git add .
    This will add all the new html doc pages for staging
7.  Run:  git commit
    Provide a comment that you are updating the documenation
    This will stage all the new html doc pages for the gh-pages branch
8.  Run:  git push
    This will push the new html doc pages to the gh-pages branch
9.  Run:  git checkout master
    This will return you to the master branch
10. Go to github.com/<your repository> and create a pull request for your changes to gh-pages
      BE SURE THAT THE PULL REQUEST IS GOING FROM your gh-pages-docs branch to brcdcomm/pybvc's gh-pages branch!!!!
      THAT IS VERY VERY IMPORTANT - you DO NOT WANT to send your gh-pages-docs changes to the master branch by accident.
10. After your pull request is accepted:  Check out the new documents (wait about 3 minutes for Github to prep them) at:  http://brcdcomm.github.io/pybvc/index.html
11. If something is wrong with the web pages you can debug them using the Google Chrome developer tools (or your browsers equivalent)
 
Background:
- Good article: http://gisellezeno.com/tutorials/sphinx-for-python-documentation.html
- Directories related to docs:
    - docs - this contains some key files NOT to be deleted
         - source/config.py - this defines how the documents are created, and html theme used, version as well.  Don't delete it.
    - howToUpdateDocs.txt - this file
    - dodoc - script to create documents