swh:1:snp:3a699297f000109a1bc833f294a54171df990207
Tip revision: 1f1c7340a3b58072225e1784e001b0e03a7b6624 authored by Josh Willis on 27 April 2016, 23:13:02 UTC
v1.3.8
v1.3.8
Tip revision: 1f1c734
build_gh_pages.rst
########################################
Building Documentation for Git Hub Pages
########################################
===============================
Creating a Git Hub project page
===============================
Git Hub pages are built from a branch of the repository called ``gh-pages``.
If you have not already created a Git Hub project pages for PyCBC in your
repository, make a ``gh-pages`` branch in your repository as follows:
.. code-block:: bash
git checkout --orphan gh-pages
git rm -rf .
git clean -dxf
touch .nojekyll
mkdir latest
git add .nojekyll latest
git commit -a -m "set up gh-pages branch"
git push origin gh-pages
git branch --set-upstream gh-pages origin/gh-pages
These commands create the branch and then remove all of the files from this branch, so that it will just contain the documentation pages.
.. note::
The main `ligo-cbc/pycbc <https://github.com/ligo-cbc/pycbc>`_ repository already has a `gh-pages` branch, so do not do this in the main repository.
======================================
Building and pushing the documentation
======================================
The documentation should built from the source code on a regular branch and installed into the ``gh-pages`` branch. Since git cannot have two branches checked out simultaneously, you need to make a copy of your repository with just the gh-pages branch checked out. Do this will the following commands (assuming your PyCBC git repository is in a directory named ``pycbc``).
.. code-block:: bash
cd /path/to/your/repo/pycbc
git checkout gh-pages
cd ..
cp -a pycbc pycbc-gh-pages
cd pycbc
git checkout master
In this example, we checkout the master branch to build the documentation, but you can change the last command above to checkout any other branch that your are developing. To generate the documentation, from the top level of the PyCBC source tree run
.. code-block:: bash
python setup.py build_gh_pages
This will build the documentation in the second repository that you created called ``pycbc-gh-pages`` under the directory ``latest/``. To push these changes up to Git Hub
.. code-block:: bash
cd ../pycbc-gh-pages
git add --all
git commit -a -m "updated documentation"
git push
The documentation will then be available under your Git Hub pages at ``http://username.github.io/pycbc/latest/html/`` where you should replace ``username/`` with your Git Hub account name.