doc: Move sphinx.errors API docs to code

This allows us to do something like 'help(sphinx.errors)' in code. We
reword the exception descriptions per Python stdlib conventions.

Signed-off-by: Stephen Finucane <stephen@that.guru>

sphinx/errors.py

@@ -16,20 +16,35 @@ if False:
 
 
 class SphinxError(Exception):
-    """
-    Base class for Sphinx errors that are shown to the user in a nicer
-    way than normal exceptions.
+    """Base class for Sphinx errors.
+
+    This is the base class for "nice" exceptions.  When such an exception is
+    raised, Sphinx will abort the build and present the exception category and
+    message to the user.
+
+    Extensions are encouraged to derive from this exception for their custom
+    errors.
+
+    Exceptions *not* derived from :exc:`SphinxError` are treated as unexpected
+    and shown to the user with a part of the traceback (and the full traceback
+    saved in a temporary file).
+
+    .. attribute:: category
+
+       Description of the exception "category", used in converting the
+       exception to a string ("category: message").  Should be set accordingly
+       in subclasses.
     """
     category = 'Sphinx error'
 
 
 class SphinxWarning(SphinxError):
-    """Raised for warnings if warnings are treated as errors."""
+    """Warning, treated as error."""
     category = 'Warning, treated as error'
 
 
 class ExtensionError(SphinxError):
-    """Raised if something's wrong with the configuration."""
+    """Extension error."""
     category = 'Extension error'
 
     def __init__(self, message, orig_exc=None):
@@ -53,27 +68,22 @@ class ExtensionError(SphinxError):
 
 
 class ConfigError(SphinxError):
+    """Configuration error."""
     category = 'Configuration error'
 
 
 class ThemeError(SphinxError):
+    """Theme error."""
     category = 'Theme error'
 
 
 class VersionRequirementError(SphinxError):
+    """Incompatible Sphinx version error."""
     category = 'Sphinx version error'
 
 
-class PycodeError(Exception):
-    def __str__(self):
-        # type: () -> str
-        res = self.args[0]
-        if len(self.args) > 1:
-            res += ' (exception was: %r)' % self.args[1]
-        return res
-
-
 class SphinxParallelError(SphinxError):
+    """Sphinx parallel build error."""
 
     category = 'Sphinx parallel build error'
 
@@ -85,3 +95,14 @@ class SphinxParallelError(SphinxError):
     def __str__(self):
         # type: () -> str
         return self.message
+
+
+class PycodeError(Exception):
+    """Pycode Python source code analyser error."""
+
+    def __str__(self):
+        # type: () -> str
+        res = self.args[0]
+        if len(self.args) > 1:
+            res += ' (exception was: %r)' % self.args[1]
+        return res