Merge lp:~johnmfl/openlp/developer_readme into lp:openlp

[Johnthan]

Updated the ReadMe.txt to ReadMe.rst and included Development Environment info.

[Raoul Snyman (raoul-snyman)]

Linux tests passed!

[Raoul Snyman (raoul-snyman)]

Linting passed!

[Phill (phill-ridout)]

I'm not sure about this. This is the page that will show up on GitLab? Has it been discussed in IRC? There seems to be some duplication with the wiki. Will this be removed from the wiki?

[Johnthan (johnmfl)]

This should be put on Hold until superfly can be involved.

Unmerged revisions

2889. By Johnthan on 2019-08-03

combined original readme.txt with readme.rst

2888. By Johnthan on 2019-08-03

Developer ReadMe added

=== added file 'README.rst'
--- README.rst	1970-01-01 00:00:00 +0000
+++ README.rst	2019-08-06 17:50:50 +0000
@@ -0,0 +1,289 @@
+OpenLP
+======
+
+You're probably reading this because you've just downloaded the source code for
+OpenLP. If you are looking for the installer file, please go to the download
+page on the web site::
+
+    http://openlp.org/download
+
+If you're looking for how to contribute to OpenLP, then please look at the
+OpenLP wiki::
+
+    http://wiki.openlp.org/
+
+Thanks for downloading OpenLP!
+
+
+OpenLP Development
+==================
+
+This repository holds the OpenLP development code and tests among other items.
+
+Getting Started
+---------------
+To get up and running with the development and testing, you'll need to install 
+the Python programing language and serveral other packages. Python version 3.6 
+or above is required, currently version 3.7 is recommended.
+
+Linux
+~~~~~
+If you're using Linux, you'll want to check your package manager for those
+packages. Below are commands to install OpenLP's dependecies on some common Linux
+distributions.
+
+Ubuntu/Debian::
+
+    $ sudo apt update
+    
+    $ sudo apt install python3 qttools5-dev-tools pyqt5-dev-tools python3-pyqt5 python3-pyqt5.qtmultimedia \
+                       python3-pyqt5.qtsvg python3-pyqt5.qtopengl python3-pyqt5.qtwebchannel python3-pyqt5.qtwebkit \
+                       python3-pyqt5.qtwebengine python3-sqlalchemy python3-chardet python3-lxml \
+                       python3-enchant python3-bs4 python3-mako python3-uno python3-nose2 python3-nose2-cov \
+                       python3-pip python3-alembic python3-xdg python3-dbus.mainloop.pyqt5 python3-pep8 \
+                       python3-websockets python3-waitress python3-webob python3-requests bzr mediainfo \
+                       pylint3 python3-qtawesome python3-opengl python3-appdirs python3-mysql-connector-python \
+                       python3-pyodbc python3-psycopg2 python3-asyncio python3-six python3-pyobjc-core \
+                       python3-pysword python3-python-vlc python3-pymupdf python3-qdarkstyle python3-pyro4 \
+                       libreoffice-pyuno python3-pytest python3-zeroconfig
+
+Fedora::
+
+    $ sudo dnf install python3-PyQt5 python3-qt5-webengine python3-sqlalchemy python3-alembic 
+                       python3-beautifulsoup4 python3-chardet python3-enchant python3-lxml python3-xdg python3-pytest 
+                       python3-websockets python3-appdirs python3-webob python3-QtAwesome python3-waitress 
+                       python3-pymediainfo python3-pyopengl python3-pysword python3-Mako python3-mysql-connector-python 
+                       python3-pyodbc python3-psycopg2 python3-asyncio python3-six python3-requests python3-pyobjc-core 
+                       python3-python-vlc python3-pymupdf python3-pylint python3-qdarkstyle python3-pyro4 python3-zeroconfig
+    
+    $ sudo dnf install libreoffice-pyuno
+
+macOS
+~~~~~
+On macOS you can install the dependencies via MacPorts or Homebrew. Below are commands
+to install OpenLP's dependencies.
+
+It is recommended that you install and use the virtual environment for Python.  
+Take a look at 'How I Setup VirtualEnv and VirtualEnvWrapper on My Mac <http://mkelsey.com/2013/04/30/how-i-setup-virtualenv-and-virtualenvwrapper-on-my-mac/>'
+if you decide to install the virtual environment.
+
+
+MacPorts with a virtual environment::
+
+    $ sudo port selfupdate
+    
+    $ sudo port install python37 py37-pip
+    
+    $ sudo port select --set python3 python37
+
+
+Install and use the virtual environment before continuing::
+
+    $ pip install sqlalchemy alembic appdirs chardet beautifulsoup4 lxml 
+                  Mako mysql-connector-python pytest pyobjc pyodbc psycopg2 websockets 
+                  asyncio waitress six webob requests pyopengl qtAwesome PyQt5 pymediainfo 
+                  pysword PyQtWebEngine python-vlc pymupdf pyenchant pylint pytest 
+                  python-jenkins launchpadlib qdarkstyle pyro4 zeroconfig
+    
+    $ pip install hunspell-dict-af_ZA hunspell-dict-ca_ES 
+                  hunspell-dict-cs_CZ hunspell-dict-cy_GB hunspell-dict-de_DE 
+                  hunspell-dict-el_GR hunspell-dict-en_CA hunspell-dict-en_GB 
+                  hunspell-dict-en_NZ hunspell-dict-en_US hunspell-dict-en_ZA 
+                  hunspell-dict-eo_EO hunspell-dict-es_ES hunspell-dict-es_MX 
+                  hunspell-dict-fo_FO hunspell-dict-fy_NL hunspell-dict-ga_IE 
+                  hunspell-dict-gd_GB hunspell-dict-gsc_FR hunspell-dict-gu_IN 
+                  hunspell-dict-he_IL hunspell-dict-hi_IN hunspell-dict-hr_HR 
+                  hunspell-dict-id_ID hunspell-dict-ku_TR hunspell-dict-lt_LT 
+                  hunspell-dict-mg_MG hunspell-dict-mk_MK hunspell-dict-ms_MY 
+                  hunspell-dict-nb_NO hunspell-dict-nl_NL hunspell-dict-nn_NO 
+                  hunspell-dict-nr_ZA hunspell-dict-ns_ZA hunspell-dict-ny_MW 
+                  hunspell-dict-oc_FR hunspell-dict-rw_RW hunspell-dict-sl_SI 
+                  hunspell-dict-ss_ZA hunspell-dict-st_ZA hunspell-dict-sw_KE 
+                  hunspell-dict-tet_ID hunspell-dict-th_TH hunspell-dict-tl_PH 
+                  hunspell-dict-tn_ZA hunspell-dict-ts_ZA hunspell-dict-uk_UA 
+                  hunspell-dict-ve_ZA hunspell-dict-xh_ZA hunspell-dict-zu_ZA
+
+MacPorts without a virtual environment::
+
+    $ sudo port selfupdate
+    
+    $ sudo port install bzr git mupdf python37
+    
+    $ sudo port select --set python3 python37
+
+    $ sudo port -N install py37-pyqt5 +webengine +webkit
+    
+    $ sudo port install py37-pip py37-lxml py37-sqlalchemy py37-mako py37-pytest 
+                        py37-beautifulsoup4 py37-psycopg2 py37-sphinx py37-sphinx_rtd_theme 
+                        py37-alembic py37-chardet py37-enchant py37-pyobjc-cocoa 
+                        py37-webob py37-waitress py37-websockets py37-qtawesome 
+                        py37-requests mediainfo hunspell-dict-af_ZA hunspell-dict-ca_ES 
+                        hunspell-dict-cs_CZ hunspell-dict-cy_GB hunspell-dict-de_DE 
+                        hunspell-dict-el_GR hunspell-dict-en_CA hunspell-dict-en_GB 
+                        hunspell-dict-en_NZ hunspell-dict-en_US hunspell-dict-en_ZA 
+                        hunspell-dict-eo_EO hunspell-dict-es_ES hunspell-dict-es_MX 
+                        hunspell-dict-fo_FO hunspell-dict-fy_NL hunspell-dict-ga_IE 
+                        hunspell-dict-gd_GB hunspell-dict-gsc_FR hunspell-dict-gu_IN 
+                        hunspell-dict-he_IL hunspell-dict-hi_IN hunspell-dict-hr_HR 
+                        hunspell-dict-id_ID hunspell-dict-ku_TR hunspell-dict-lt_LT 
+                        hunspell-dict-mg_MG hunspell-dict-mk_MK hunspell-dict-ms_MY 
+                        hunspell-dict-nb_NO hunspell-dict-nl_NL hunspell-dict-nn_NO 
+                        hunspell-dict-nr_ZA hunspell-dict-ns_ZA hunspell-dict-ny_MW 
+                        hunspell-dict-oc_FR hunspell-dict-rw_RW hunspell-dict-sl_SI 
+                        hunspell-dict-ss_ZA hunspell-dict-st_ZA hunspell-dict-sw_KE 
+                        hunspell-dict-tet_ID hunspell-dict-th_TH hunspell-dict-tl_PH 
+                        hunspell-dict-tn_ZA hunspell-dict-ts_ZA hunspell-dict-uk_UA 
+                        hunspell-dict-ve_ZA hunspell-dict-xh_ZA hunspell-dict-zu_ZA
+
+    $ sudo port install py37-appdirs py37-mysql-connector-python py37-pyodbc py37-asyncio 
+                        py37-six py37-pyopengl py37-pysword py37-python py37-pylint 
+                        py37-qdarkstyle py37-pyro4 py37-zeroconfig
+    
+Homebrew::
+
+    $ sudo brew update
+    
+    $ sudo brew install bzr git wget vim htop-osx
+    
+    $ sudo brew install qt --with-qtwebkit
+    
+    $ sudo brew install postgresql python3 enchant
+    
+    $ sudo pip3 install sqlalchemy alembic appdirs chardet beautifulsoup4 lxml Mako 
+                        mysql-connector-python pyodbc psycopg2 websockets asyncio 
+                        waitress six webob requests QtAwesome PyQt5 PyQtWebEngine 
+                        pymediainfo pyobjc-core pysword PyOpenGL python-vlc pymupdf 
+                        pyenchant pylint python-jenkins launchpadlib qdarkstyle pyro4
+                        pytest zeroconfig
+
+Manual:
+    
+Install python by downloading the current version from the 'Python Download Website <https://www.python.org/downloads/mac-osx/>'
+then install the packages using python and pip::
+    
+    $ pyhon3 -m pip install sqlalchemy alembic appdirs chardet beautifulsoup4 lxml Mako 
+                            mysql-connector-python nose mock pyodbc psycopg2 websockets asyncio 
+                            waitress six webob requests QtAwesome PyQt5 PyQtWebEngine 
+                            pymediainfo pyobjc-core pysword PyOpenGL python-vlc pymupdf 
+                            pyenchant pylint python-jenkins launchpadlib qdarkstyle pyro4 pytest zeroconfig
+
+Windows
+~~~~~~~
+On Windows you'll need to download and install the Python Windows 
+Installer from the 'Python download page <http://python.org/download>'
+
+Download and Install VLC for Windows from the 'VLC download page <https://www.videolan.org/vlc/download-windows.html>'
+You must install the correct version of VLC to match the version of 
+Python you installed.  If you installed the 32 bit version of Python 
+then install the 32 bit version of VLC.  If you installed the 64 bit 
+version of Python, then you must install the 64 bit version of VLC.
+
+It is recommended that you install and use the virtual environment 
+for Python.  Take a look at the 'Python Vertual Environment <http://timmyreilly.azurewebsites.net/python-pip-virtualenv-installation-on-windows/>'
+to help decide if you will install the virtual environment.
+
+Use ``pip`` to install the addin packages that are needed for OpenLP::
+    
+    pip install sqlalchemy alembic appdirs chardet beautifulsoup4 lxml 
+                Mako mysql-connector-python pytest pyodbc psycopg2 pypiwin32 websockets 
+                asyncio waitress six webob requests pyopengl qtAwesome PyQt5 pymediainfo 
+                pywin32 pysword PyQtWebEngine python-vlc pymupdf pyenchant pylint 
+                python-jenkins launchpadlib qdarkstyle pyro4 zeroconfig
+    
+    
+Verify Installation
+-------------------
+
+Once you have completed the steps above, check the install is successful by 
+launching python script in a command prompt:
+
+Linux
+~~~~~
+
+Open a terminal, enter your Virtual Environment if you installed one, then navigate 
+to the openlp directory.  The openlp directory should have a scripts
+directory.  Once you are there, type in the following line and press enter.
+
+    ``python3 scripts/check_dependencies.py``
+
+Windows
+~~~~~~~
+
+Open a command prompt, enter your Virtual Environment if you created one and 
+navigate to the openlp directory.  The openlp directory should have a scripts
+directory.  Once you are there, type in the following line and press enter.
+
+    ``python scripts\check_dependencies.py``
+    
+MacOSx
+~~~~~~
+
+Open a terminal, enter your Virtual Environment if you installed one, then navigate 
+to the openlp directory.  The openlp directory should have a scripts
+directory.  Once you are there, type in the following line and press enter.
+
+    ``python3 scripts/check_dependencies.py``
+
+.. warning: 
+   Only from the top to the Optional packages are manditory as some 
+   packages do not run on all platforms...see ``uno`` below as an example.
+
+The output should look similar to this::
+
+    Checking Python version...
+      Python >= 3.6 ...                    3.7.3.final.0
+    Checking for modules...
+      PyQt5 ...                            OK
+      PyQt5.QtCore ...                     OK
+      PyQt5.QtGui ...                      OK
+      PyQt5.QtWidgets ...                  OK
+      PyQt5.QtNetwork ...                  OK
+      PyQt5.QtOpenGL ...                   OK
+      PyQt5.QtSvg ...                      OK
+      PyQt5.QtTest ...                     OK
+      PyQt5.QtWebEngineWidgets ...         OK
+      PyQt5.QtMultimedia ...               OK
+      appdirs ...                          OK
+      sqlalchemy ...                       OK
+      alembic ...                          OK
+      lxml ...                             OK
+      chardet ...                          OK
+      bs4 ...                              OK
+      mako ...                             OK
+      websockets ...                       OK
+      waitress ...                         OK
+      webob ...                            OK
+      requests ...                         OK
+      qtawesome ...                        OK
+      pymediainfo ...                      OK
+      vlc ...                              OK
+      zeroconf ...                         OK
+    Checking for optional modules...
+      qdarkstyle (dark style support)...   OK
+      mysql.connector (MySQL support)...   OK
+      pyodbc (ODBC support)...             OK
+      psycopg2 (PostgreSQL support)...     OK
+      enchant (spell checker)...           OK
+      fitz (executable-independent PDF support)...  OK
+      pysword (import SWORD bibles)...     OK
+      uno (LibreOffice/OpenOffice support)...  FAIL
+      jenkins (access jenkins api)...      OK
+      launchpadlib (launchpad script support)...  OK
+      pytest (testing framework)...        OK
+      pylint (linter)...                   OK
+    Checking for Windows specific modules...
+      win32com ...                         OK
+      win32ui ...                          OK
+      pywintypes ...                       OK
+    Verifying version of modules...
+      PyQt5 >= 5.12 ...                    5.12.2
+      Qt5 >= 5.9 ...                       5.12.3
+      sqlalchemy >= 0.5 ...                1.3.5
+      enchant >= 1.6 ...                   2.0.0
+    Qt5 image formats...
+      read: bmp, cur, gif, icns, ico, jpeg, jpg, pbm, pgm, png, ppm, svg, svgz, tga, tif, tiff, wbmp, webp, xbm, xpm
+      write: bmp, cur, icns, ico, jpeg, jpg, pbm, pgm, png, ppm, tif, tiff, wbmp, webp, xbm, xpm
+    Enchant (spell checker)...
+      available backends: ispell, myspell
+      available languages: de_DE, en_AU, en_GB, en_US, fr_FR
+    

=== removed file 'README.txt'
--- README.txt	2014-05-03 15:28:31 +0000
+++ README.txt	1970-01-01 00:00:00 +0000
@@ -1,15 +0,0 @@
-OpenLP
-======
-
-You're probably reading this because you've just downloaded the source code for
-OpenLP. If you are looking for the installer file, please go to the download
-page on the web site::
-
-    http://openlp.org/download
-
-If you're looking for how to contribute to OpenLP, then please look at the
-OpenLP wiki::
-
-    http://wiki.openlp.org/
-
-Thanks for downloading OpenLP!