From: Kaliko Jack <kaliko@azylum.org>
Date: Fri, 16 Nov 2018 15:38:37 +0000 (+0100)
Subject: Improved documentation
X-Git-Tag: v0.4.3~5
X-Git-Url: https://git.kaliko.me/?a=commitdiff_plain;h=3701fc9d2658323a423476695e550224f2cb7343;p=python-musicpd.git

Improved documentation
---

diff --git a/CHANGES.txt b/CHANGES.txt
index ada6427..9b24aeb 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -5,6 +5,7 @@ Changes in 0.4.3 UNRELEASED
 ---------------------------
 
 * Use setuptools
+* Add sphinx documentation
 * Add sensible defaults and honor environment variables
   Use MPD_HOST/MPD_PORT (honor password setting in MPD_HOST)
   If MPD_HOST is not set, tries to find a socket in
diff --git a/MANIFEST.in b/MANIFEST.in
index 3305050..b5cd761 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,3 +1,2 @@
-exclude setup.cfg
-include *.txt README.rst
-recursive-include doc *.txt
+include *.txt
+recursive-include doc *
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 9038c86..8df63f2 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -18,7 +18,6 @@
 #
 import os
 import sys
-# sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('../../'))
 from musicpd import VERSION
 __author__ = 'kaliko'
@@ -127,7 +126,6 @@ todo_include_todos = True
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
 html_theme = 'classic'
 #html_theme = "sphinx_rtd_theme"
 #html_theme = 'bootstrap'
diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst
index cf87c1c..26ac918 100644
--- a/doc/source/contribute.rst
+++ b/doc/source/contribute.rst
@@ -8,13 +8,14 @@ Git Workflow
 * ``master`` branch holds latest stable|release code
 * ``dev`` branch holds current development code
 * Work on a dedicated branch starting off ``dev``
-* I like fast forward merges, **please rebase on** ``dev`` **branch**
+* I like fast forward merges, **please rebase on** ``dev`` branch before submitting changes
 * Advertise your work (cf. Note)
 
 .. NOTE::
     **Git merge Workflow** |br|
     I currently don't care about a specific workflow concerning changes submission. |br|
-    gitlab merge request, gh pull request, plain email pointing out a repo/ref. All we need is a public git repo and a ref to fetch from as long you rebased on ``dev`` branch.
+    Don't bother with gitlab merge request or gh pull request. |br|
+    All we need is a public git repo and a ref to fetch from as long you rebased on ``dev`` branch.
 
 Coding
 -------
diff --git a/musicpd.py b/musicpd.py
index 1a7fd97..0d241ee 100644
--- a/musicpd.py
+++ b/musicpd.py
@@ -104,9 +104,22 @@ class _NotConnected:
         raise ConnectionError("Not connected")
 
 class MPDClient:
-    """MPDClient instance will look for ``MPD_HOST``/``MPD_PORT`` environment
+    """MPDClient instance will look for ``MPD_HOST``/``MPD_PORT``/``XDG_RUNTIME_DIR`` environment
     variables and set instance attribute ``host``, ``port`` and ``password``
     accordingly.
+
+    Then :py:obj:`musicpd.MPDClient.connect` will use ``host`` and ``port`` as defaults if not provided as args.
+
+    Cf. :py:obj:`musicpd.MPDClient.connect` for details.
+
+    >>> from os inport environ
+    >>> environ['MPD_HOST'] = 'pass@mpdhost'
+    >>> cli = musicpd.MPDClient()
+    >>> cli.password == environ['MPD_HOST'].split('@')[0]
+    True
+    >>> cli.host == environ['MPD_HOST'].split('@')[1]
+    True
+    >>> # cli.connect() will use host/port as set in MPD_HOST/MPD_PORT
     """
 
     def __init__(self):
@@ -538,9 +551,9 @@ class MPDClient:
         .. note:: Default host/port
 
           If host evaluate to :py:obj:`False`
-           * if ``MPD_HOST`` env. var. is set, use it for host
+           * use ``MPD_HOST`` env. var. if set, extract password if present,
            * else looks for a existing file in ``${XDG_RUNTIME_DIR:-/run/}/mpd/socket``
-           * finally set host to ``localhost``
+           * else set host to ``localhost``
 
           If port evaluate to :py:obj:`False`
            * if ``MPD_PORT`` env. var. is set, use it for port
@@ -566,8 +579,8 @@ class MPDClient:
 
     def disconnect(self):
         """Closes the MPD connection.
-        The client closes the actual socket and not using the
-        'close' request from MPD protocol as suggested in documentation.
+        The client closes the actual socket, it does not use the
+        'close' request from MPD protocol (as suggested in documentation).
         """
         if hasattr(self._rfile, 'close'):
             self._rfile.close()