... | ... | @@ -6,148 +6,165 @@ |
|
|
- [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
|
|
|
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>)
|
|
|
## Installing Sphinx and Sphinx RTD Theme
|
|
|
|
|
|
Below are the instructions for installing Sphinx on each of the platforms.
|
|
|
|
|
|
### 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.
|
|
|
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 the latest version of Python 3.
|
|
|
|
|
|
The recommended way to install additional Python dependencies in Windows
|
|
|
is via `pip`. You can do this easily using
|
|
|
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:
|
|
|
Once pip-Win is installed, select your Python executable (usually `C:\Python3\python.exe`) and type the following into the \*Command\* box:
|
|
|
|
|
|
```
|
|
|
pip install Sphinx sphinx_rtd_theme
|
|
|
```
|
|
|
|
|
|
### macOS
|
|
|
|
|
|
To install Sphinx on macOS, you need to already have MacPorts or Homebrew installed. Once MacPorts or Homebrew are installed, you can install Sphinx.
|
|
|
|
|
|
#### For MacPorts
|
|
|
|
|
|
`pip install Sphinx`
|
|
|
Depending which version of Python you have installed, you'll need to install the version of Sphinx for your Python. For instance, if you have Python 3.9 installed, you'll need to run the following command:
|
|
|
|
|
|
### Mac OS X
|
|
|
```
|
|
|
$ sudo port install py39-sphinx py39-sphinx_rtd_theme
|
|
|
```
|
|
|
|
|
|
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.
|
|
|
If you don't have Python installed yet, install the 3.10 version of Sphinx, and it'll install Python too:
|
|
|
|
|
|
For MacPorts:
|
|
|
```
|
|
|
$ sudo port install py310-sphinx py310-sphinx_rtd_theme
|
|
|
```
|
|
|
|
|
|
`$ sudo port install py34-sphinx`
|
|
|
#### For Homebrew
|
|
|
|
|
|
For Homebrew:
|
|
|
First, install Sphinx:
|
|
|
|
|
|
`$ brew install sphinx-doc`
|
|
|
```
|
|
|
$ brew install sphinx-doc
|
|
|
```
|
|
|
|
|
|
### Ubuntu
|
|
|
Homebrew does not package the Sphinx RTD Theme, so we'll need to install it separately:
|
|
|
|
|
|
To install Sphinx in Ubuntu, install it from the Ubuntu repositories:
|
|
|
```
|
|
|
$ sudo pip install sphinx_rtd_theme
|
|
|
```
|
|
|
|
|
|
` $ sudo apt-get install python3-sphinx`
|
|
|
### Debian / Ubuntu
|
|
|
|
|
|
To install Sphinx on Debian or Ubuntu, install it from the repositories:
|
|
|
|
|
|
```
|
|
|
$ sudo apt-get install python3-sphinx python3-sphinx_rtd_theme
|
|
|
```
|
|
|
|
|
|
### Fedora
|
|
|
|
|
|
To install Sphinx in Fedora, install it from the Fedora repositories:
|
|
|
|
|
|
` # yum install python-sphinx`
|
|
|
```
|
|
|
$ sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme
|
|
|
```
|
|
|
|
|
|
### openSUSE
|
|
|
|
|
|
To install Sphinx in openSUSE, install it from the openSUSE
|
|
|
repositories:
|
|
|
To install Sphinx in openSUSE, install it from the openSUSE repositories:
|
|
|
|
|
|
` $ sudo zypper install python-sphinx`
|
|
|
```
|
|
|
$ sudo zypper install python-sphinx python-sphinx_rtd_theme
|
|
|
```
|
|
|
|
|
|
### Arch Linux
|
|
|
|
|
|
To install Sphinx in Arch Linux, install it from the Arch Linux
|
|
|
repositories:
|
|
|
To install Sphinx in Arch Linux, install it from the Arch Linux repositories:
|
|
|
|
|
|
` # pacman -S python2-sphinx`
|
|
|
```
|
|
|
# pacman -S python-sphinx python-sphinx_rtd_theme
|
|
|
```
|
|
|
|
|
|
### 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.
|
|
|
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:
|
|
|
First install `virtualenv` from your package manager. Then create a virtual environment:
|
|
|
|
|
|
` $ virtualenv --system-site-packages --python=python3 venv`
|
|
|
```
|
|
|
$ virtualenv --system-site-packages --python=python3 venv
|
|
|
```
|
|
|
|
|
|
`virtualenv` installs `pip` for you, so now you can install Sphinx:
|
|
|
|
|
|
` $ ./venv/bin/pip install Sphinx`
|
|
|
```
|
|
|
$ ./venv/bin/pip install Sphinx sphinx_rtd_theme
|
|
|
```
|
|
|
|
|
|
## 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.
|
|
|
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").
|
|
|
For full details on how to get your work submitted and approved please see the section on [Development
|
|
|
Workflow](Development/Workflow#version-control-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:
|
|
|
OpenLP uses the Git DVCS ([read more about Git](Git "wikilink")). After setting up git on your computer, do the following to clone the documentation repository:
|
|
|
|
|
|
> **Note:** If your chosen editor has a Git client, you can probably do the following in there.
|
|
|
|
|
|
|
|
|
1. Fork the documentation repository on GitLab using the `Fork` button
|
|
|
2. Clone your fork to your computer:
|
|
|
```shell
|
|
|
$ git clone git@gitlab.com:myusername/documentation.git
|
|
|
```
|
|
|
3. Set up the main repository as your upstream remote:
|
|
|
```shell
|
|
|
$ cd documentation
|
|
|
$ git remote add upstream https://gitlab.com/openlp/documentation.git
|
|
|
```
|
|
|
4. Now you can create a new branch for your work, using the aliases set up in the Git article:
|
|
|
```shell
|
|
|
$ git br my-new-branch
|
|
|
```
|
|
|
5. Work on your documentation
|
|
|
6. Commit your work:
|
|
|
```shell
|
|
|
$ git commit -am "Updated the settings page"
|
|
|
```
|
|
|
7. Push your changes up to your GitLab project:
|
|
|
```shell
|
|
|
$ git push origin my-new-branch
|
|
|
```
|
|
|
8. Once your changes have been pushed up to GitLab, visit GitLab to create a **Merge Request**
|
|
|
|
|
|
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.
|
|
|
When a new feature is added or a bug fixed which requires a change in the documentation, the developers may log an issue to the [documentation issues](https://gitlab.com/openlp/documentation/issues). 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 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)
|
|
|
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).
|
|
|
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.
|
|
|
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.
|
|
|
If you are using the OpenLP Windows builder script (windows-builder.py), these steps will be performed for you.
|
|
|
|
|
|
[Documentation/Pages](Documentation/Pages "wikilink") |
|
|
[Documentation/Pages](Documentation/Pages "wikilink") |
|
|
\ No newline at end of file |