Okydoky is an automated documentation builder using Sphinx, GitHub and Distribute (which was setuptools). It makes your closed Python project to continuously build documentations, with the following assumptions:
- Documentation is done using Sphinx.
- Project is packaged through setuptools (not pip nor any others).
- Source code is managed under GitHub.
To say shortly, it's simply a ReadTheDocs.org for private use.
How it works
It works in the following instructions:
- When new commits are pushed, GitHub triggers Okydoky post-receive hook.
- Okydoky downloads tarball archives of pushed commits from GitHub.
- Tarball archive gets extracted into a temporary directory.
- Sphinx builds the documentation.
- When users request the docs using their web browser, Okydoky asks the user to authenticate using GitHub OAuth.
- If they has the authorization, Okydoky serves a built docs.
How to use
It's an ordinary Python package. You can install it using
$ easy_install Okydoky
This package provides a command line script called
It's a web application and also a small web server for itself.
It takes a config file <config>.
Config files have to contain some required values like GitHub application key and secret key.
You have to create a GitHub application to use Okydoky. Its Callback URL is very important. Fill it with:
<host> with the domain name what you'll use. And then,
add a post-receive hook into your GitHub repository:
If you make a config file, then run an Okydoky server using
$ okydoky -H 0.0.0.0 -p 8080 yourconfig.py
Lastly, you have to make an initial auth to finish installation.
http://<host>/ in your web browser and login with GitHub from there.
The config file is a normal Python script. It uses Flask's config system. Read Flask's docs about config files.
- The user and repository name e.g.
- The GitHub application's client key.
- The GitHub application's secret key.
- The path of the directory to store data. This directory will store some configured data, tarballs, and built documentations.
- The secret key to sign sessions. See Flask's docs about sessions also.
Creates the new virtualenv for every build. It's a lot slower than not using this, but instead makes free from side effects related
Set any nonzero value e.g.
Trueif you want to recreate the virtualenv everytime.
The callback function (any callable object) which is called when the build has complete. It's called for each commit, even if it failed.
It takes three positional parameters:
basestring) Commit hash
basestring) Permalink of the docs. It might be 404 if the build failed.
sys.exc_info()function returns if the build failed.
Noneif the build succeeded.
You can utilize the last argument for printing the error traceback e.g.:
import traceback def COMPLETE_HOOK(commit_id, permalink, exc_info): if exc_info is not None: traceback.print_exception(*exc_info)
Special environment variable:
Okydoky sets the special environment variable named
its build process. You can determine whether it's built by Okydoky or not.
For example, you can add some additional requirements only for Okydoky build
import os from setuptools import setup install_requires = ['Flask', 'SQLAlchemy'] if os.environ.get('OKYDOKY'): install_requires.extend(['Sphinx', 'sphinxcontrib-httpdomain']) setup( name='YourProject', install_requires=install_requires )
conf.py for Sphinx:
import os if os.environ.get('OKYDOKY'): html_theme = 'nature' else: html_theme = 'default'
$ git clone git://github.com/crosspop/okydoky.git
To be released.
- A quick fix of hiding of some private repositories when there are many repositories in the organization. [#7 by Jökull Sólberg Auðunsson]
Released on February 12, 2013.
RECREATE_VIRTUALENVoption which makes it to create the virtualenv for each build.
- Try recreating the virtualenv if the build has failed first.
--proxy-fixoption for HTTP reverse proxies.
- Don't use github-distutils anymore to prevent several headaches related packaging and distribution.
Released on September 16, 2012.
- GitHub forced
statefor OAuth. Follow that.
Released on September 3, 2012.
setup.py developcommand. This prevents version conflicts of dependencies.
- Build logs are left in the
Released on July 18, 2012.
- Now the index page shows the list of refs.
- Now Okydoky sets
OKYDOKY=1environment variable during its build process. [#5]
/headspecial ref url.
- Fixed a bug that the head is not set to the latest commit.
Released on July 17, 2012. Hotfix of 0.9.1.
- Fixed a security bug: now users must have an authorization for the repository. [#4]
Released on July 17, 2012. Hotfix of 0.9.0.
okydokypackage empty and moved things to
Released on July 17, 2012.
- Initial version.