To build the docs, you’ll need a couple of packages:
- graphiz
- sphinx (installed with anaconda)
- sphinx-bootstrap-theme
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
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 .
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
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.
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
Simply build the sphinx docs now with your build directory as docs!:
> cd dev/VOCAL/calipso
> sphinx-build -b html ../docs/source ../../../docs/VOCAL
Move the index.html you saved earlier back to the docs/VOCAL folder and overwrite the file
created by Sphinx.
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