Documentation:Getting Started

From OpenLP

Contents 1 Introduction 1.1 Installing Sphinx 1.1.1 Microsoft Windows 1.1.2 Ubuntu 1.1.3 Fedora 1.1.4 OpenSuse 1.1.5 Arch Linux 1.1.6 Using EasyInstall on Linux 2 reStructuredText and Using Sphinx 3 Submitting Your Work 4 Windows Help Files

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

Microsoft Windows

You will want to use EasyInstall to install Sphinx on windows.

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

Then Download ez_setup.py and run it. (you will probably need to right click the link and click save as)

Bring up a command prompt and run:

C:\> C:\Python26\scripts\easy_install.exe Sphinx

Ubuntu

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

 user@linux:~$sudo apt-get install python-sphinx

Fedora

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

 root@linux:~#yum install python-sphinx

OpenSuse

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

 user@linux:~$sudo zypper install python-sphinx

Arch Linux

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

 root@linux:~#pacman -S python-sphinx

Using EasyInstall on Linux

 user@linux:~$easy_install -U Sphinx

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.

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.

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.