Building Automated Documentation with Okydoky

Are you tired of manually building documentation for your Python projects? Look no further, as Okydoky is here to automate the process for you! In this article, we will explore how Okydoky, in conjunction with Sphinx, GitHub, and Distribute, can continuously build documentation for your closed projects. By the end, you’ll have a solid understanding of how to set up Okydoky, configure it, and serve your project’s documentation.

How Okydoky Works

Okydoky follows a straightforward series of instructions to build and serve your project’s documentation:

1. Once new commits are pushed, GitHub triggers Okydoky’s post-receive hook.
2. Okydoky downloads the tarball archives of the pushed commits from GitHub.
3. The tarball archive is extracted into a temporary directory.
4. Sphinx builds the documentation.
5. When users request the documentation through their web browser, Okydoky asks for authentication using GitHub OAuth.
6. If users are authorized, Okydoky serves the built documentation.

Getting Started with Okydoky

To get started with Okydoky, you’ll need to install it as an ordinary Python package. You can use the easy_install command to install it:

console
$ easy_install Okydoky

Once installed, you can use the okydoky command-line script to run Okydoky as a web application and server. This script requires a configuration file, which contains important values like your GitHub application key and secret key.

To create a GitHub application for Okydoky, make sure to set the Callback URL to: http://<host>/auth/finalize, replacing <host> with your domain name. Additionally, add a post-receive hook to your GitHub repository: http://<host>/.

Once you have a config file, you can run the Okydoky server using the okydoky script:

console
$ okydoky -H 0.0.0.0 -p 8080 yourconfig.py

Finally, to complete the installation, make an initial authentication by opening http://<host>/ in your web browser and logging in with your GitHub account.

Configuring Okydoky

The Okydoky configuration file is a regular Python script that uses Flask’s config system. All configurations are defined within this file. Here are some of the key configuration options:

• REPOSITORY: The user and repository name, e.g., 'crosspop/okydoky'.
• CLIENT_ID: The GitHub application’s client key.
• CLIENT_SECRET: The GitHub application’s secret key.
• SAVE_DIRECTORY: The path to the directory where data, tarballs, and built documentation will be stored.
• SECRET_KEY: The secret key used to sign sessions.
• RECREATE_VIRTUALENV: Set to any nonzero value if you want to recreate the virtualenv for every build.
• COMPLETE_HOOK: A callback function called when the build is complete.

The configuration file provides more detailed information on each option and how to set them up. Make sure to consult Flask’s documentation on config files for further guidance.

Open Source and Licensing

Okydoky is an open-source project developed by Hong Minhee for Crosspop. It is distributed under the MIT license, and you can find the source code in the GitHub repository.

Conclusion

Automating the documentation building process for your Python projects has never been easier with Okydoky. By integrating with Sphinx, GitHub, and Distribute, Okydoky streamlines the process of building and serving documentation for your closed projects. In this article, we covered the installation and configuration of Okydoky, as well as its workflow and key features. Now it’s your turn to try it out and experience the benefits of automated documentation building. Happy documenting!

References:
– Okydoky GitHub Repository
– Flask’s Config Documentation
– GitHub API Documentation
– Sphinx Documentation