[Pkg-mpd-commits] [python-mpd] 209/262: restructure README.rst for new documentation
Simon McVittie
smcv at debian.org
Sun May 22 18:16:48 UTC 2016
This is an automated email from the git hooks/post-receive script.
smcv pushed a commit to branch upstream
in repository python-mpd.
commit c0164d7a4f6e8dbef387467247dabe8a8d250666
Author: Jörg Thalheim <joerg at higgsboson.tk>
Date: Tue Jun 25 08:25:36 2013 +0200
restructure README.rst for new documentation
---
INSTALL.rst | 48 +++++++++
README.rst | 222 +++++------------------------------------
doc/index.rst | 7 ++
doc/topics/getting-started.rst | 3 -
setup.cfg | 5 +
5 files changed, 85 insertions(+), 200 deletions(-)
diff --git a/INSTALL.rst b/INSTALL.rst
new file mode 100644
index 0000000..c52d35e
--- /dev/null
+++ b/INSTALL.rst
@@ -0,0 +1,48 @@
+PyPI:
+~~~~~
+
+::
+
+ $ pip install python-mpd2
+
+Debian
+~~~~~~
+
+Drop this line in */etc/apt/sources.list.d/python-mpd2.list*::
+
+ deb http://sima.azylum.org/debian unstable main
+
+Import the gpg key as root::
+
+ $ wget -O - http://sima.azylum.org/sima.gpg | apt-key add -
+
+Key fingerprint::
+
+ 2255 310A D1A2 48A0 7B59 7638 065F E539 32DC 551D
+
+Controls with *apt-key finger*.
+
+Then simply update/install *python-mpd2* or *python3-mpd* with apt or
+aptitude:
+
+Arch Linux
+~~~~~~~~~~
+
+Install `python-mpd2 <http://aur.archlinux.org/packages.php?ID=59276>`__
+from AUR.
+
+Gentoo Linux
+~~~~~~~~~~~~
+
+Replaces the original python-mpd beginning with version 0.4.2::
+
+ $ emerge -av python-mpd
+
+FreeBSD
+~~~~~~~
+
+Install *py-mpd2*::
+
+ $ pkg_add -r py-mpd2
+
+Packages for other distributions are welcome!
diff --git a/README.rst b/README.rst
index 0188204..e2fa1ed 100644
--- a/README.rst
+++ b/README.rst
@@ -47,17 +47,6 @@ copy of the development version from Git by running the command::
$ git clone git://github.com/Mic92/python-mpd2.git
-Installing from source
-----------------------
-
-To install *python-mpd2* from source, simply run the command::
-
- $ python setup.py install
-
-You can use the *--help* switch to *setup.py* for a complete list of commands
-and their options. See the `Installing Python Modules
-<http://docs.python.org/inst/inst.html>`__ document for more details.
-
Getting the latest release
--------------------------
@@ -71,203 +60,31 @@ PyPI:
$ pip install python-mpd2
+Installation in Linux/BSD distributions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
Until Linux distributions adapt this package, here are some ready to use
packages to test your applications:
-Debian
-~~~~~~
-
-Drop this line in */etc/apt/sources.list.d/python-mpd2.list*::
-
- deb http://sima.azylum.org/debian unstable main
-
-Import the gpg key as root::
-
- $ wget -O - http://sima.azylum.org/sima.gpg | apt-key add -
-
-Key fingerprint::
-
- 2255 310A D1A2 48A0 7B59 7638 065F E539 32DC 551D
-
-Controls with *apt-key finger*.
-
-Then simply update/install *python-mpd2* or *python3-mpd* with apt or
-aptitude:
-
-Arch Linux
-~~~~~~~~~~
-
-Install `python-mpd2 <http://aur.archlinux.org/packages.php?ID=59276>`__
-from AUR.
-
-Gentoo Linux
-~~~~~~~~~~~~
-
-Replaces the original python-mpd beginning with version 0.4.2::
-
- $ emerge -av python-mpd
-
-FreeBSD
-~~~~~~~
-
-Install *py-mpd2*::
-
- $ pkg_add -r py-mpd2
-
-Packages for other distributions are welcome!
-
-Using the client library
-------------------------
-
-The client library can be used as follows::
-
- >>> client = mpd.MPDClient() # create client object
- >>> client.timeout = 10 # network timeout in seconds (floats allowed), default: None
- >>> client.idletimeout = None # timeout for fetching the result of the idle command is handled seperately, default: None
- >>> client.connect("localhost", 6600) # connect to localhost:6600
- >>> print(client.mpd_version) # print the MPD version
- >>> print(client.find("any", "house")) # print result of the command "find any house"
- >>> client.close() # send the close command
- >>> client.disconnect() # disconnect from the server
-
-A list of supported commands, their arguments (as MPD currently understands
-them), and the functions used to parse their responses can be found in
-*doc/commands.txt*. See the `MPD protocol documentation
-<http://www.musicpd.org/doc/protocol/>`__ for more details.
-
-Command lists are also supported using *command\_list\_ok\_begin()* and
-*command\_list\_end()*::
-
- >>> client.command_list_ok_begin() # start a command list
- >>> client.update() # insert the update command into the list
- >>> client.status() # insert the status command into the list
- >>> results = client.command_list_end() # results will be a list with the results
-
-Commands may also return iterators instead of lists if *iterate* is set
-to *True*::
-
- client.iterate = True
- for song in client.playlistinfo():
- print song["file"]
-
-Each command have a *send\_* and a *fetch\_* variant, which allows to send a MPD
-command and then fetch the result later. This is useful for the idle command::
+See `INSTALL.rst <INSTALL.rst>`__
- >>> client.send_idle()
- # do something else or use function like select(): http://docs.python.org/howto/sockets.html#non-blocking-sockets
- # ex. select([client], [], []) or with gobject: http://jatreuman.indefero.net/p/python-mpd/page/ExampleIdle/
- >>> events = client.fetch_idle()
-
-Some more complex usage examples can be found
-`here <http://jatreuman.indefero.net/p/python-mpd/doc/>`_
-
-Range
------
-
-Some commands support integer ranges as argument. This is done in python-mpd2
-by using two element tuple::
-
- # move the first three songs
- # after the last in the playlist
- >>> client.status()
- ['file: song1.mp3',
- 'file: song2.mp3',
- 'file: song3.mp3',
- 'file: song4.mp3']
- >>> client.move((0,3), 1)
- >>> client.status()
- ['file: song4.mp3'
- 'file: song1.mp3',
- 'file: song2.mp3',
- 'file: song3.mp3',]
-
-Second element can be omitted. MPD will assumes the biggest possible number then (don't forget the comma!)::
-NOTE: mpd versions between 0.16.8 and 0.17.3 contains a bug, so ommiting doesn't work.
-
- >>> client.delete((1,)) # delete all songs, but the first.
-
-
-Unicode Handling
-----------------
-
-To quote the mpd protocol documentation:
-
-> All data to be sent between the client and server must be encoded in UTF-8.
-
-With Python 3:
-~~~~~~~~~~~~~~
-
-In Python 3, Unicode string is the default string type. So just pass these
-strings as arguments for MPD commands and *python-mpd2* will also return such
-Unicode string.
-
-With Python 2.x
-~~~~~~~~~~~~~~~
-
-For backward compatibility with *python-mpd*, when running with Python 2.x,
-*python-mpd2* accepts both Unicode strings (ex. u"♥") and UTF-8 encoded strings
-(ex. "♥").
-
-In order for *MPDClient* to return Unicode strings with Python 2, create the
-instance with the ``use_unicode`` parameter set to ``True``.
-
-Using Unicode strings should be prefered as it is done transparently by the
-library for you, and makes the transition to Python 3 easier::
-
- >>> import mpd
- >>> client = MPDClient(use_unicode=True)
- >>> client.urlhandlers()[0]
- u'http'
- >>> client.use_unicode = False # Can be switched back later
- >>> client.urlhandlers()[0]
- 'http'
-
-Using this option in Python 3 doesn't have any effect.
-
-Logging
--------
-
-By default messages are sent to the logger named ``mpd``::
-
- >>> import logging, mpd
- >>> logging.basicConfig(level=logging.DEBUG)
- >>> client = mpd.MPDClient()
- >>> client.connect("localhost", 6600)
- INFO:mpd:Calling MPD connect('localhost', 6600, timeout=None)
- >>> client.find('any', 'dubstep')
- DEBUG:mpd:Calling MPD find('any', 'dubstep')
-
-For more information about logging configuration, see
-http://docs.python.org/2/howto/logging.html
-
-Future Compatible
------------------
-
-New commands or special handling of commands can be easily implemented. Use
-``add_command()`` or ``remove_command()`` to modify the commands of the
-*MPDClient* class and all its instances.::
+Installing from source
+----------------------
- def fetch_cover(client):
- """"Take a MPDClient instance as its arguments and return mimetype and image"""
- # this command may come in the future.
- pass
+To install *python-mpd2* from source, simply run the command::
- self.client.add_command("get_cover", fetch_cover)
- # you can then use:
- self.client.fetch_cover()
+ $ python setup.py install
- # remove the command, because it doesn't exist already.
- self.client.remove_command("get_cover")
+You can use the *--help* switch to *setup.py* for a complete list of commands
+and their options. See the `Installing Python Modules
+<http://docs.python.org/inst/inst.html>`__ document for more details.
-Thread-Safety
+Documentation
-------------
-Currently ``MPDClient`` is **NOT** thread-safe. As it use a socket internaly,
-only one thread can send or receive at the time.
+`Getting Started`
-But ``MPDClient`` can be easily extended to be thread-safe using `locks
-<http://docs.python.org/library/threading.html#lock-objects>`__. Take a look at
-``examples/locking.py`` for further informations.
+`Command Reference`
Testing
-------
@@ -280,6 +97,17 @@ This will install `Tox <http://tox.testrun.org/>`__. Tox will take care of
testing against all the supported Python versions (at least available) on our
computer, with the required dependencies
+Building Documentation
+----------------------
+
+Install Sphinx::
+
+ $ easy_install -U Sphinx
+
+Change to the source directory an run::
+
+ $ python ./setup.py build_sphinx
+
Contacting the author
---------------------
diff --git a/doc/index.rst b/doc/index.rst
index 73e2815..7a26286 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -44,6 +44,13 @@ A quick guide for getting started python-mpd2:
.. _python-mpd: http://jatreuman.indefero.net/p/python-mpd/
+Command Reference
+=================
+
+A complete list of all available commands:
+
+* :doc:`Commands <topics/commands>`
+
Changelog
=========
diff --git a/doc/topics/getting-started.rst b/doc/topics/getting-started.rst
index 95e0dee..36344cc 100644
--- a/doc/topics/getting-started.rst
+++ b/doc/topics/getting-started.rst
@@ -43,9 +43,6 @@ command and then fetch the result later. This is useful for the idle command::
Some more complex usage examples can be found
`here <http://jatreuman.indefero.net/p/python-mpd/doc/>`_
-Range
------
-
Some commands support integer ranges as argument. This is done in python-mpd2
by using two element tuple::
diff --git a/setup.cfg b/setup.cfg
index 75d2fcb..f1fe3ec 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,2 +1,7 @@
[sdist]
formats=bztar,gztar,zip
+
+[build_sphinx]
+source-dir = doc/
+build-dir = doc/_build
+all_files = 1
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-mpd/python-mpd.git
More information about the Pkg-mpd-commits
mailing list