|
|
|
<!-- toc -->
|
|
|
|
- [Introduction](#introduction)
|
|
|
|
- [Installing Sphinx (<span class="color:#f00;">mandatory</span>)](#installing-sphinx-span-classcolorf00mandatoryspan)
|
|
|
|
- [Submitting Your Work](#submitting-your-work)
|
|
|
|
- [Check out the latest code](#check-out-the-latest-code)
|
|
|
|
- [Documentation Tasks](#documentation-tasks)
|
|
|
|
- [reStructuredText and Using Sphinx](#restructuredtext-and-using-sphinx)
|
|
|
|
- [Windows Help Files](#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](http://sphinx.pocoo.org/rest.html). For info on the Sphinx
|
|
|
|
Python Documentation Generator visit their
|
|
|
|
[site](http://sphinx.pocoo.org/).
|
|
|
|
|
|
|
|
## Installing Sphinx (<span class="color:#f00;">mandatory</span>)
|
|
|
|
|
|
|
|
### Windows
|
|
|
|
|
|
|
|
You will first need to install Python on your system. Download and
|
|
|
|
install the Python Windows Installer from [Python download
|
|
|
|
page](http://python.org/download/). 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](https://sites.google.com/site/pydatalog/python/pip-for-windows).
|
|
|
|
|
|
|
|
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`
|
|
|
|
|
|
|
|
## 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](Development/Workflow "wikilink").
|
|
|
|
|
|
|
|
## Check out the latest code
|
|
|
|
|
|
|
|
<div style="float: right; width: 128px; text-align: right;">
|
|
|
|
|
|
|
|
![Python\_code.png](Python_code.png "Python_code.png")
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
OpenLP uses the Bazaar DVCS ([read more about
|
|
|
|
Bazaar](Bazaar "wikilink")) 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](https://bugs.launchpad.net/openlp/documentation). 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](http://sphinx.pocoo.org/rest.html)
|
|
|
|
|
|
|
|
For information on using and building documentation with Sphinx, please
|
|
|
|
check out [the Sphinx
|
|
|
|
documentation.](http://sphinx.pocoo.org/contents.html)
|
|
|
|
|
|
|
|
## 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](http://msdn.microsoft.com/en-us/library/ms669985%28v=vs.85%29.aspx).
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
[Documentation/Pages](Documentation/Pages "wikilink") |