Documentation:Getting Started

From OpenLP
Jump to: navigation, search

Introduction

In OpenLP we use reStructuredText to form all of the documentation using the Sphinx build tool to build the documentation. For information on reStructuredText go to the editing reStructuredText primer. For info on the Sphinx Python Documentation Generator visit their site.

Installing Sphinx (mandatory)

Windows

You will first need to install Python on your system. Download and install the Python Windows Installer from Python download page. You need to install Python 3.4.

The recommended way to install additional Python dependencies in Windows is via pip. You can do this easily using pip-Win.

Once pip-Win is installed, select your Python executable (usually C:\Python34\python.exe) and type the following into the *Command* box:

pip install Sphinx

Mac OS X

To install Sphinx on Mac OS X, you need to already have MacPorts or Homebrew installed. Once MacPorts or Homebrew are installed, you can install Sphinx.

For MacPorts:

$ sudo port install py34-sphinx

For Homebrew:

$ brew install sphinx-doc

Ubuntu

To install Sphinx in Ubuntu, install it from the Ubuntu repositories:

 $ sudo apt-get install python3-sphinx

Fedora

To install Sphinx in Fedora, install it from the Fedora repositories:

 # yum install python-sphinx

openSUSE

To install Sphinx in openSUSE, install it from the openSUSE repositories:

 $ sudo zypper install python-sphinx

Arch Linux

To install Sphinx in Arch Linux, install it from the Arch Linux repositories:

 # pacman -S python2-sphinx

Using pip on Linux

If Sphinx is unavailable for your platform, you can install it via pip. It is recommended to make a virtual environment and then install Sphinx in there.

First install virtualenv from your package manager. Then create a virtual environment:

 $ virtualenv --system-site-packages --python=python3 venv

virtualenv installs pip for you, so now you can install Sphinx:

 $ ./venv/bin/pip install Sphinx

Sign up to Launchpad (mandatory)

Launchpad logo.png

If you don't yet have a Launchpad username, you'll need to sign up for one. In order to commit code back into the main branch, you'll need to have a Launchpad username, and will need to apply to be added to the OpenLP Development team on Launchpad. Once you're on Launchpad, you can propose a merge.

Don't forget to upload your public SSH key, as shown on the pages for Windows and Linux/Mac OS X.

Why Bazaar/Why Launchpad

Folks often come into our IRC channel and ask why we chose Bazaar and Launchpad for development. The reality is that Launchpad was launched in January 2004, while Github was only launched in April 2008. At the time that OpenLP moved from SourceForge.net (where it had been since 2004), Launchpad was the only other widely known online source code repository. Since Bazaar's workflow closely resembles that of Subversion, the version control system OpenLP was coming from, it seemed a natural progression. At the time, git was also extremely small and unsupported by most online source code repositories. After two repository moves and three version control moves, OpenLP is going to stay where it is.

Submitting Your Work

Submitting documentation for OpenLP follows the same workflow as for those submitting code to be used in OpenLP. Being a programmer is not required to write documentation for OpenLP but we will be using some of the same tools as they do to submit documentation.

For full details on how to get your work submitted and approved please see the section on Development Workflow.

Check out the latest code

Python code.png

OpenLP uses the Bazaar DVCS (read more about Bazaar) and the main branch is hosted at Launchpad.net. Do the following to set up your local branch:

  1. Identify yourself to Bazaar:
    $ bzr whoami "Raoul Snyman <raoulsnyman@example.com>"
  2. Log in to Launchpad:
    $ bzr launchpad-login raoul-snyman
  3. Create a shared repository:
    $ bzr init-repo ~/openlp-docs
  4. Checkout the latest code:
    $ bzr checkout lp:openlp/documentation ~/openlp-docs/trunk

Documentation Tasks

When a new feature is added or a bug fixed which requires a change in the documentation, the developers will often assign the bug report to the documentation bug queue. This is a good place to look for documentation that needs to be written.

reStructuredText and Using Sphinx

For information on the formatting for reStructuredText please see the reStructuredText primer

For information on using and building documentation with Sphinx, please check out the Sphinx documentation.

Windows Help Files

If you are planning to make Windows help files (.CHM) or plan on preforming a Windows build you will need to install HTML Help Workshop.

To create the Windows help files, you need to run Sphinx with the htmlhelp option. Then run hhc_exe (the help compiler) pointing to the output folder created by the Sphinx command.

If you are using the OpenLP Windows builder script (windows-builder.py), these steps will be performed for you.