Adds docs for xonsh.platform

docs/api/platform.rst

@@ -3,9 +3,56 @@
 Platform-specific constants and implementations (``xonsh.platform``)
 ====================================================================
 
+Functions
+---------
 
 .. automodule:: xonsh.platform
-    :members:
-    :undoc-members:
-    :inherited-members:
+    :members: has_prompt_toolkit, is_readline_available, ptk_version,
+              ptk_version_info
+
+.. py:module:: xonsh.platform
+
+
+Constants
+---------
+
+
+.. autodata:: BASH_COMPLETIONS_DEFAULT
+    :annotation:
+
+.. autodata:: BEST_SHELL_TYPE
+    :annotation:
+
+.. autodata:: DEFAULT_ENCODING
+    :annotation:
+
+.. autodata:: HAS_PYGMENTS
+    :annotation:
+
+.. autodata:: LINUX_DISTRO
+    :annotation:
+
+.. autodata:: ON_ANACONDA
+    :annotation:
+
+.. autodata:: ON_DARWIN
+    :annotation:
+
+.. autodata:: ON_LINUX
+    :annotation:
+
+.. autodata:: ON_POSIX
+    :annotation:
+
+.. autodata:: ON_WINDOWS
+    :annotation:
+
+.. autodata:: PLATFORM_INFO
+    :annotation:
+
+.. autodata:: PYGMENTS_VERSION
+    :annotation:
+
+.. autodata:: PYTHON_VERSION_INFO
+    :annotation:
 

xonsh/platform.py

@@ -23,10 +23,14 @@ except:
 #
 
 ON_DARWIN = platform.system() == 'Darwin'
+""" ``True`` if executed on a Darwin platform, else ``False``. """
 ON_LINUX = platform.system() == 'Linux'
+""" ``True`` if executed on a Linux platform, else ``False``. """
 ON_WINDOWS = platform.system() == 'Windows'
+""" ``True`` if executed on a Windows platform, else ``False``. """
 
 ON_POSIX = (os.name == 'posix')
+""" ``True`` if executed on a POSIX-compliant platform, else ``False``. """
 
 
 
@@ -35,12 +39,20 @@ ON_POSIX = (os.name == 'posix')
 #
 
 PYTHON_VERSION_INFO = sys.version_info[:3]
+""" Version of Python interpreter as three-value tuple. """
 ON_ANACONDA = any(s in sys.version for s in {'Anaconda', 'Continuum'})
+""" ``True`` if executed in an Anaconda instance, else ``False``. """
+
+
+HAS_PYGMENTS = False
+""" ``True`` if `pygments` is available, else ``False``. """
+PYGMENTS_VERSION = None
+""" `pygments.__version__` version if available, else ``Ǹone``. """
 
 try:
     import pygments
 except ImportError:
-    HAS_PYGMENTS, PYGMENTS_VERSION = False, None
+    pass
 except:
     raise
 else:
@@ -49,6 +61,7 @@ else:
 
 @lru_cache(1)
 def has_prompt_toolkit():
+    """ Tests if the `prompt_toolkit` is available. """
     try:
         import prompt_toolkit
     except ImportError:
@@ -61,6 +74,7 @@ def has_prompt_toolkit():
 
 @lru_cache(1)
 def ptk_version():
+    """ Returns `prompt_toolkit.__version__` if available, else ``None``. """
     if has_prompt_toolkit():
         import prompt_toolkit
         return getattr(prompt_toolkit, '__version__', '<0.57')
@@ -70,12 +84,16 @@ def ptk_version():
 
 @lru_cache(1)
 def ptk_version_info():
+    """ Returns `prompt_toolkit`'s version as tuple of integers. """
     if has_prompt_toolkit():
         return tuple(int(x) for x in ptk_version().strip('<>+-=.').split('.'))
     else:
         return None
 
 
+BEST_SHELL_TYPE = None
+""" The 'best' available shell type, either 'prompt_toollit' or 'readline'. """
+
 if ON_WINDOWS or has_prompt_toolkit():
     BEST_SHELL_TYPE = 'prompt_toolkit'
 else:
@@ -96,12 +114,19 @@ def is_readline_available():
 #
 
 DEFAULT_ENCODING = sys.getdefaultencoding()
+""" Default string encoding. """
 
 
 #
 # Linux distro
 #
 
+LINUX_DISTRO = None
+""" The id of the Linux distribution running on, possibly 'unknown'.
+    ``Ǹone`` on non-Linux platforms.
+"""
+
+
 if ON_LINUX:
     if distro:
         LINUX_DISTRO = distro.id()
@@ -111,8 +136,6 @@ if ON_LINUX:
         LINUX_DISTRO = 'arch'  # that's the only one we need to know for now
     else:
         LINUX_DISTRO = 'unknown'
-else:
-    LINUX_DISTRO = None
 
 
 #
@@ -132,6 +155,11 @@ else:
 # Bash completions defaults
 #
 
+BASH_COMPLETIONS_DEFAULT = ()
+""" A possibly empty tuple with default paths to Bash completions known for
+    the current platform.
+"""
+
 if LINUX_DISTRO == 'arch':
     BASH_COMPLETIONS_DEFAULT = (
         '/etc/bash_completion',
@@ -151,12 +179,10 @@ elif ON_WINDOWS:
         progamfiles + '/Git/usr/share/bash-completion/completions',
         progamfiles + '/Git/mingw64/share/git/completion/git-completion.bash')
 
-else:
-    BASH_COMPLETIONS_DEFAULT = ()
-
 #
 # All constants as a dict
 #
 
 PLATFORM_INFO = {name: obj for name, obj in globals().items()
                  if name.isupper()}
+""" The constants of this module as dictionary. """