update doc

2 files changed, 87 insertions, 56 deletions

diff --git a/docs/conf.py b/docs/conf.py
index df825cbd..b056d20f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -110,7 +110,7 @@ language = None
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'DEVGUIDE.rst']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
diff --git a/docs/index.rst b/docs/index.rst
index 94713f54..45fd3758 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1230,34 +1230,49 @@ Process class
 
   .. method:: ionice(ioclass=None, value=None)
 
-    Get or set process I/O niceness (priority). On Linux *ioclass* is one of the
-    :data:`psutil.IOPRIO_CLASS_*<psutil.IOPRIO_CLASS_NONE>` constants.
-    *value* is a number which goes from  ``0`` to ``7``. The higher the value,
-    the lower the I/O priority of the process. On Windows only *ioclass* is
-    used and it can be set to ``2`` (normal), ``1`` (low) or ``0`` (very low).
-    The example below sets IDLE priority class for the current process,
-    meaning it will only get I/O time when no other process needs the disk:
-
-      >>> import psutil
-      >>> p = psutil.Process()
-      >>> p.ionice(psutil.IOPRIO_CLASS_IDLE)  # set
-      >>> p.ionice()  # get
-      pionice(ioclass=<IOPriority.IOPRIO_CLASS_IDLE: 3>, value=0)
-      >>>
-
-    On Windows only *ioclass* is used and it can be set to ``3`` (high),
-    ``2`` (normal), ``1`` (low) or ``0`` (very low).
-    Also it returns an integer instead of a named tuple.
-
-    Availability: Linux and Windows > Vista
-
-    .. versionchanged::
-      Windows accepts ``3`` (high) value.
-
-    .. versionchanged::
-      3.0.0 on Python >= 3.4 the returned ``ioclass`` constant is an
-      `enum <https://docs.python.org/3/library/enum.html#module-enum>`__
-      instead of a plain integer.
+    Get or set process I/O niceness (priority).
+    If no argument is provided it acts as a get, returning a ``(ioclass, value)``
+    tuple on Linux and a *ioclass* integer on Windows.
+    If *ioclass* is provided it acts as a set. In this case an additional
+    *value* can be specified on Linux only in order to increase or decrease the
+    I/O priority even further.
+    Here's the possible platform-dependent *ioclass* values.
+
+    Linux (see `ioprio_get`_ manual):
+
+    * ``IOPRIO_CLASS_RT``: (high) the process gets first access to the disk
+      every time. Use it with care as it can starve the entire
+      system. Additional priority *level* can be specified and ranges from
+      ``0`` (highest) to ``7`` (lowest).
+    * ``IOPRIO_CLASS_BE``: (normal) the default for any process that hasn't set
+      a specific I/O priority. Additional priority *level* ranges from
+      ``0`` (highest) to ``7`` (lowest).
+    * ``IOPRIO_CLASS_IDLE``: (low) get I/O time when no-one else needs the disk.
+      No additional *value* is accepted.
+    * ``IOPRIO_CLASS_NONE``: returned when no priority was previously set.
+
+    Windows:
+
+    * ``IOPRIO_HIGH``: highest priority.
+    * ``IOPRIO_NORMAL``: default priority.
+    * ``IOPRIO_LOW``: low priority.
+    * ``IOPRIO_VERYLOW``: lowest priority.
+
+    Here's an example on how to set the highest I/O priority depending on what
+    platform you're on::
+
+      import psutil
+      p = psutil.Process()
+      if psutil.LINUX
+          p.ionice(psutil.IOPRIO_CLASS_RT, level=7)
+      else:  # Windows
+          p.ionice(psutil.IOPRIO_HIGH)
+      p.ionice()  # get
+
+    Availability: Linux, Windows Vista+
+
+    .. versionchanged:: 5.6.2 Windows accepts mew ``IOPRIO_*`` constants
+     including new ``IOPRIO_HIGH``.
 
   .. method:: rlimit(resource, limits=None)
 
@@ -2034,6 +2049,9 @@ Example code:
 Constants
 =========
 
+Operating system constants
+--------------------------
+
 .. _const-oses:
 .. data:: POSIX
 .. data:: WINDOWS
@@ -2054,7 +2072,7 @@ Constants
 
 .. data:: OSX
 
-  Alias for :const:`MACOS` (deprecated).
+  Alias for :const:`MACOS`.
 
   .. warning::
     deprecated in version 5.4.7; use :const:`MACOS` instead.
@@ -2078,6 +2096,9 @@ Constants
   .. versionchanged:: 3.4.2 also available on Solaris.
   .. versionchanged:: 5.4.0 also available on AIX.
 
+Process status constants
+------------------------
+
 .. _const-pstatus:
 .. data:: STATUS_RUNNING
 .. data:: STATUS_SLEEPING
@@ -2094,39 +2115,21 @@ Constants
 .. data:: STATUS_WAITING (FreeBSD)
 .. data:: STATUS_SUSPENDED (NetBSD)
 
-  A set of strings representing the status of a process.
   Returned by :meth:`psutil.Process.status()`.
 
   .. versionadded:: 3.4.1 STATUS_SUSPENDED (NetBSD)
   .. versionadded:: 5.4.7 STATUS_PARKED (Linux)
 
-.. _const-conn:
-.. data:: CONN_ESTABLISHED
-.. data:: CONN_SYN_SENT
-.. data:: CONN_SYN_RECV
-.. data:: CONN_FIN_WAIT1
-.. data:: CONN_FIN_WAIT2
-.. data:: CONN_TIME_WAIT
-.. data:: CONN_CLOSE
-.. data:: CONN_CLOSE_WAIT
-.. data:: CONN_LAST_ACK
-.. data:: CONN_LISTEN
-.. data:: CONN_CLOSING
-.. data:: CONN_NONE
-.. data:: CONN_DELETE_TCB (Windows)
-.. data:: CONN_IDLE (Solaris)
-.. data:: CONN_BOUND (Solaris)
-
-  A set of strings representing the status of a TCP connection.
-  Returned by :meth:`psutil.Process.connections()` (`status` field).
+Process priority constants
+--------------------------
 
 .. _const-prio:
-.. data:: ABOVE_NORMAL_PRIORITY_CLASS
-.. data:: BELOW_NORMAL_PRIORITY_CLASS
+.. data:: REALTIME_PRIORITY_CLASS
 .. data:: HIGH_PRIORITY_CLASS
-.. data:: IDLE_PRIORITY_CLASS
+.. data:: ABOVE_NORMAL_PRIORITY_CLASS
 .. data:: NORMAL_PRIORITY_CLASS
-.. data:: REALTIME_PRIORITY_CLASS
+.. data:: IDLE_PRIORITY_CLASS
+.. data:: BELOW_NORMAL_PRIORITY_CLASS
 
   A set of integers representing the priority of a process on Windows (see
   `SetPriorityClass`_). They can be used in conjunction with
@@ -2160,7 +2163,6 @@ Constants
 
   Availability: Linux
 
-.. _const-ioprio:
 .. data:: IOPRIO_VERYLOW
 .. data:: IOPRIO_LOW
 .. data:: IOPRIO_NORMAL
@@ -2174,7 +2176,9 @@ Constants
 
   .. versionadded:: 5.6.2
 
-.. _const-rlimit:
+Process resources constants
+---------------------------
+
 .. data:: RLIM_INFINITY
 .. data:: RLIMIT_AS
 .. data:: RLIMIT_CORE
@@ -2199,6 +2203,33 @@ Constants
 
   Availability: Linux
 
+Connections constants
+---------------------
+
+.. _const-conn:
+.. data:: CONN_ESTABLISHED
+.. data:: CONN_SYN_SENT
+.. data:: CONN_SYN_RECV
+.. data:: CONN_FIN_WAIT1
+.. data:: CONN_FIN_WAIT2
+.. data:: CONN_TIME_WAIT
+.. data:: CONN_CLOSE
+.. data:: CONN_CLOSE_WAIT
+.. data:: CONN_LAST_ACK
+.. data:: CONN_LISTEN
+.. data:: CONN_CLOSING
+.. data:: CONN_NONE
+.. data:: CONN_DELETE_TCB (Windows)
+.. data:: CONN_IDLE (Solaris)
+.. data:: CONN_BOUND (Solaris)
+
+  A set of strings representing the status of a TCP connection.
+  Returned by :meth:`psutil.Process.connections()` and
+  :func:`psutil.net_connections` (`status` field).
+
+Hardware constants
+------------------
+
 .. _const-aflink:
 .. data:: AF_LINK