From 1ef87caf5e6e692f9056c4520e2a991a843f2d38 Mon Sep 17 00:00:00 2001 From: Christian Jacobs Date: Tue, 13 Feb 2018 21:01:19 +0000 Subject: [PATCH 1/4] Adding more explanation about PyQSO's dependencies. --- README.md | 83 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 42 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 988f69e..94512ff 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - Copyright (C) 2013-2017 Christian Thomas Jacobs. + Copyright (C) 2013-2018 Christian Thomas Jacobs. This file is part of PyQSO. @@ -15,61 +15,37 @@ You should have received a copy of the GNU General Public License along with PyQSO. If not, see . -PyQSO -===== +# PyQSO PyQSO is a contact logging tool for amateur radio operators. [![Build Status](https://travis-ci.org/ctjacobs/pyqso.svg)](https://travis-ci.org/ctjacobs/pyqso) [![Documentation Status](https://readthedocs.org/projects/pyqso/badge/?version=latest)](https://readthedocs.org/projects/pyqso/?badge=latest) -Installation and running ------------------------- +## Dependencies -Assuming that the current working directory is PyQSO's base directory (the directory that the `Makefile` is in), PyQSO can be run without installation by issuing the following command in the terminal: +As the name suggests, PyQSO is written primarily in the [Python](https://www.python.org/) programming language (version 3.x). The graphical user interface has been developed using the [GTK+ library](https://www.gtk.org/) through the [PyGObject bindings](https://pygobject.readthedocs.io). Therefore, before PyQSO can be installed, the Python interpreter must be present on your system along with support for GTK+. On many Linux-based systems this can be accomplished by installing the following Debian packages: - python3 bin/pyqso - -If the `pip3` package manager is available on your system then PyQSO can be installed system-wide using: - - sudo make install - -Once installed, the following command will run PyQSO: - - pyqso - -Documentation -------------- - -The PyQSO documentation is stored in the `docs` directory. It can be built with the following command: - - make docs - -which will produce an HTML version of the documentation in `docs/build/html` that can be opened in a web browser. - -Alternatively, a ready-built version of the PyQSO documentation can be found on [Read the Docs](http://pyqso.readthedocs.io/). - -Dependencies ------------- - -PyQSO depends on the following Debian packages: - -* gir1.2-gtk-3.0 * python3 -* python3-gi-cairo (for log printing purposes) +* gir1.2-gtk-3.0 +* python3-gi-cairo -The following extra packages are necessary to fully enable the grey line tool and the plotting of logbook statistics: +Several extra packages are necessary to enable the full functionality of PyQSO, such as the grey line tool. Many of these (specified in the `requirements.txt` file) can be readily installed system-wide using the Python package manager by issuing the following command in the terminal: + + sudo pip3 install -U -r requirements.txt + +but the complete list is given below: * python3-matplotlib (version 1.3.0 or later) * python3-mpltoolkits.basemap * python3-numpy * libxcb-render0-dev * python3-cairocffi -* [geocoder](https://pypi.python.org/pypi/geocoder) (installable with `pip3` and used for QTH lookups) +* [geocoder](https://pypi.python.org/pypi/geocoder) (for QTH lookups) +* python3-sphinx (for building the documentation) +* python3-hamlib (for Hamlib support) -The following extra package is necessary to build the documentation: - -* python3-sphinx +### Hamlib support There currently does not exist a Python 3-compatible Debian package for [Hamlib](http://www.hamlib.org). This library must be built manually to enable Hamlib support. As per the instructions on the [Hamlib mailing list](https://sourceforge.net/p/hamlib/mailman/message/35692744/), run the following commands in the Hamlib root directory (you may need to run `sudo apt-get install build-essential autoconf automake libtool` beforehand): @@ -83,7 +59,32 @@ You will also need to append the Hamlib `bindings` and `bindings/.libs` director export PYTHONPATH=$PYTHONPATH:/path/to/hamlib/bindings:/path/to/hamlib/bindings/.libs -Contact -------- +## Installing and running + +Assuming that the current working directory is PyQSO's base directory (the directory that the `Makefile` is in), PyQSO can be run without installation by issuing the following command in the terminal: + + python3 bin/pyqso + +If the Python package manager `pip3` is available on your system then PyQSO can be installed system-wide using: + + sudo make install + +Once installed, the following command will run PyQSO: + + pyqso + +## Documentation + +Guidance on how to use PyQSO is available on [Read the Docs](http://pyqso.readthedocs.io/) and in the screencast below. + +[![PyQSO: A Logging Tool for Amateur Radio Operators](https://img.youtube.com/vi/sVdZl9KnDsk/0.jpg)](https://www.youtube.com/watch?v=sVdZl9KnDsk) + +The documentation can also be built locally with the following command: + + make docs + +which will produce an HTML version of the documentation in `docs/build/html` that can be opened in a web browser. + +## Contact If you have any comments or questions about PyQSO please send them via email to Christian Jacobs, M0UOS, at . From 89f1ca46b47a835ac5035e0bfb7dbc5df3ced483 Mon Sep 17 00:00:00 2001 From: Christian Jacobs Date: Tue, 13 Feb 2018 21:02:22 +0000 Subject: [PATCH 2/4] Small improvements to the Getting Started section. --- docs/source/getting_started.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 3ff528e..2f518a5 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -8,11 +8,11 @@ It is recommended that users run PyQSO on the Linux operating system, since all development and testing of PyQSO takes place there. As the name suggests, PyQSO is written primarily in the `Python `_ -programming language (version 3.x). The graphical user interface has been built using +programming language (version 3.x). The graphical user interface has been developed using the `GTK+ library `_ through the `PyGObject bindings `_. PyQSO also uses an `SQLite `_ embedded database to manage all the contacts an amateur radio operator makes. Users must therefore make sure that the Python -interpreter and any additional software dependencies are satisfied +interpreter is installed and that any additional software dependencies are satisfied before PyQSO can be run successfully. The list of software packages that PyQSO depends on is provided in the ``README.md`` file. From ee6018b04a243b444706871e0e2bec7a32bf2bfd Mon Sep 17 00:00:00 2001 From: Christian Jacobs Date: Tue, 13 Feb 2018 21:02:41 +0000 Subject: [PATCH 3/4] Added a requirements.txt file for the purpose of installing dependencies. Addresses issue #63. --- requirements.txt | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 requirements.txt diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..e0a74fd --- /dev/null +++ b/requirements.txt @@ -0,0 +1,6 @@ +numpy +matplotlib>=1.3.0 +basemap +cairocffi +sphinx +geocoder From 26e871bcab8d2b6b1f818cc3c33b1cc444af8926 Mon Sep 17 00:00:00 2001 From: Christian Jacobs Date: Tue, 13 Feb 2018 21:05:23 +0000 Subject: [PATCH 4/4] Small improvement to the wording. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 94512ff..f861dcd 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ PyQSO is a contact logging tool for amateur radio operators. ## Dependencies -As the name suggests, PyQSO is written primarily in the [Python](https://www.python.org/) programming language (version 3.x). The graphical user interface has been developed using the [GTK+ library](https://www.gtk.org/) through the [PyGObject bindings](https://pygobject.readthedocs.io). Therefore, before PyQSO can be installed, the Python interpreter must be present on your system along with support for GTK+. On many Linux-based systems this can be accomplished by installing the following Debian packages: +As the name suggests, PyQSO is written primarily in the [Python](https://www.python.org/) programming language (version 3.x). The graphical user interface has been developed using the [GTK+ library](https://www.gtk.org/) through the [PyGObject bindings](https://pygobject.readthedocs.io). Therefore, in order to run PyQSO, the Python interpreter must be present on your system along with support for GTK+. On many Linux-based systems this can be accomplished by installing the following Debian packages: * python3 * gir1.2-gtk-3.0