Merge pull request #22 from davidjb/master

Add Sphinx-based documentation; convert existing docstrings

.gitignore

@@ -5,6 +5,7 @@
 *.egg-info
 dist
 build
+docs/_build
 
 # Eclipse project info
 .project
@@ -24,3 +25,6 @@ tools/init
 # Unit tests / coverage reports
 .coverage
 htmlcov
+
+# Working copy files
+*.swp

README.rst

@@ -0,0 +1,120 @@
+python-gsmmodem 
+===============
+*GSM modem module for Python*
+
+python-gsmmodem is a module that allows easy control of a GSM modem attached
+to the system. It also includes a couple of useful commandline utilities for
+interacting with a GSM modem. 
+
+Its features include:
+
+- simple methods for sending SMS messages, checking signal level, etc
+- easy-to-use API for starting and responding to USSD sessions and making voice
+  calls
+- handling incoming phone calls and received SMS messages via callback methods
+- support for SMS PDU and text mode
+- support for tracking SMS status reports
+- wraps AT command errors into Python exceptions by default
+- modular design; you easily issue your own AT commands to the modem (with
+  error  checking), or read/write directly from/to the modem if you prefer
+- comprehensive test suite
+
+Bundled utilities:
+
+- **GSMTerm**: an easy-to-use serial terminal for communicating with an
+  attached GSM modem. It features command completion, built-in help for many AT
+  commands, history, context-aware prompt, etc.
+- **sendsms.py**: a simple command line script to send SMS messages
+- **identify-modem.py**: simple utility to identify attached modem. Can also be
+  used to provide debug information used for development of python-gsmmodem. 
+
+Requirements
+------------
+
+- Python 2.6 or later
+- pyserial
+
+
+How to install this package
+---------------------------
+
+There are two ways to install ``python-gsmmodem``:
+
+Automatic installation
+~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    pip install python-gsmmodem
+
+`pip <http://www.pip-installer.org>`_ will automatically download and install
+all dependencies, as required. You can also utilise ``easy_install`` in the
+same manner as using ``pip`` above.  
+
+If you are utilising ``python-gsmmodem`` as part of another project,
+add it to your ``install_requires`` section of your ``setup.py`` file and
+upon your project's installation, it will be pulled in automatically.
+
+Manual installation
+~~~~~~~~~~~~~~~~~~~
+
+Download and extract the ``python-gsmmodem`` archive from `PyPI
+<https://pypi.python.org/pypi/python-gsmmodem>`_ for the current release
+version, or clone from `GitHub <https://github.com/faucamp/python-gsmmodem>`_.
+Next, do this::
+
+    python setup.py install
+
+Note that ``python-gsmmodem`` relies on ``pyserial`` for serial communications: 
+http://pyserial.sourceforge.net
+
+
+Testing the package
+-------------------
+
+.. |Build Status| image::  https://travis-ci.org/faucamp/python-gsmmodem.png?branch=master
+.. _Build Status: https://travis-ci.org/faucamp/python-gsmmodem
+
+
+.. |Coverage Status| image::  https://coveralls.io/repos/faucamp/python-gsmmodem/badge.png?branch=master
+.. _Coverage Status: https://coveralls.io/r/faucamp/python-gsmmodem
+
+|Build Status|_ |Coverage Status|_
+
+To run all unit tests, do::
+
+    python setup.py test
+
+Unit test code coverage information may be generated by using `coverage
+<https://pypi.python.org/pypi/coverage/>`_. You can execute it directly from
+setup.py by doing::
+
+    python setup.py coverage
+
+This will run all unit tests and report on code coverage statistics.
+
+
+Building documentation
+----------------------
+
+This package contains `Sphinx <http://sphinx-doc.org>`_-based documentation.
+To manually build or test the documentation locally, do the following::
+
+   git clone https://github.com/faucamp/python-gsmmodem.git
+   cd python-gsmmodem
+   pip install .[doc]
+   cd doc
+   make html
+
+For true isolation, you may wish to run the above commands within a
+`virtualenv <http://www.virtualenv.org/>`_, which will help you manage
+this development installation.
+
+License information
+-------------------
+
+Copyright (C) 2013 Francois Aucamp  
+See AUTHORS for all authors and contact information. 
+
+License: GNU Lesser General Public License, version 3 or later; see COPYING
+         included in this archive for details.

docs/Makefile

@@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/python-gsmmodem.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/python-gsmmodem.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/python-gsmmodem"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/python-gsmmodem"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."