GitHub Related Information¶

Python Startkladde is hosted on GitHub and the Sphinx generated html documentation is published on GitHub Project Pages.

The following sections describe how to set up the documentation and how to clone and push to the repository.

Software Development¶

Getting the source code¶

The source code can be checked out using

git clone git@github.com:claashk/python-startkladde.git

if ssh credentials for user claashk are available or via https with

git clone https://github.com/claashk/python-startkladde.git

Workflow¶

Bug reports, feature requests and other issues should be reported in the GitHub Issue Tracker.

Contributers are encouraged to use the fork & pull development strategie based on pull requests.

Publishing Documentation with GitHub Project Pages¶

GitHub allows to upload html documentation in a separate branch called gh-pages. The html documentation is then available at http://claashk.github.io/python-startkladde.

Setting Up the Branch¶

Setting up the branch follows the GitHub documentation. To initalize the gh-pages branch with the automatically created documentation created by Sphinx in the doc/build/html, it is required to clone the entire repository into this directory:

cd doc/build/
git clone git@github.com:claashk/python-startkladde.git html
cd html
git checkout --orphan gh-pages
git rm -rf .

This creates an orphan gh-pages branch without any content.

Disabling Jekyll¶

Additionally the Jekyll Tool installed on GitHub has to be disabled, to avoid that files and directories starting with an underscore are ignored. This can be achieved by simply adding a file called ./doc/build/html/.nojekyll to the base directory of the new branch:

touch .nojekyll
git add .nojekyll

Creating and Publishing Documentation¶

The documentation can be created as usual by calling

make html

in ./doc.

To publish the such created documentation on GitHub, the gh-pages branch has to be commited and pushed to GitHub

cd doc/build/html
git add *
git commit -a -m "Uploaded current documentation to GitHub"
git push github gh-pages