Updating The SiteΒΆ

To build the docs, you’ll need a couple of packages:

Note

This site is generated with sphinx . do not attempt to modify the html files of this site, instead refer to the Building and Writing Docs page

The easiest way to built the site would be keeping two repositories of VOCAL active, and keep one for developing, the other for docs. For this example the development is done on the master branch, and the website will always be on the gh-pages branch.

Cloning the Repositories

  1. First, go ahead and clone two repositories into the workplace of your choice.:

    > mkdir dev
    > cd dev
    > git clone https://github.com/NASA-DEVELOP/VOCAL.git .
    > cd ..
    > mkdir docs
    > cd docs
    > git clone https://github.com/NASA-DEVELOP/VOCAL.git .
    
  2. Now, we have two folders, your development folder dev and your documentation site docs. You’ll need to switch the docs repository to gh-pages.:

    > cd docs/VOCAL
    > git checkout gh-pages
    
  3. Copy index.html from the docs/VOCAL folder and place it somewhere else. The index.html used on the site is different than the one generated by Sphinx. We want to save it for later to put back into the docs/VOCAL folder after the docs have been built.

  4. So you can now go on and write code, develop and create additional docs in your dev/VOCAL workspace. When you’re finally ready to rebuild the site , this will require you to clear your docs/VOCAL branch and populate it with your new generated docs.

    Warning

    It is very important you specify a directory when using the rm command. trust me

    > rm -rf docs/VOCAL/*
    > cd vocal
    
  5. Simply build the sphinx docs now with your build directory as docs!:

    > cd dev/VOCAL/calipso
    > sphinx-build -b html ../docs/source ../../../docs/VOCAL
    
  6. Move the index.html you saved earlier back to the docs/VOCAL folder and overwrite the file created by Sphinx.

  7. Head inside your docs folder, force commit the changes and the site should be live:

    > cd docs/VOCAL
    > git add *
    > git commit -m "Put a brief message here"
    > git push --force