Docs: enable intersphinx mapping for various libraries

Add intersphinx mapping to python standard library documentation and of
various direct dependency libraries:

 * `click`
 * `flask`
 * `flask_restful`
 * `kiwipy`
 * `plumpy`

Adding this documentation interconnection allows references in our docs
like :py:exc:`ValueError` to now directly link to the relevant external
documentation. This also allows to cut down the "nitpick exceptions"
quite dramatically.

aiida/cmdline/params/options/interactive.py

@@ -106,7 +106,7 @@ def get_default(self, ctx):
         return None
 
     def _get_default(self, ctx):
-        """provides the functionality of :func:`click.Option.get_default`"""
+        """provides the functionality of :meth:`click.Option.get_default`"""
         if self._contextual_default is not None:
             default = self._contextual_default(ctx)
         else:

aiida/engine/processes/calcjobs/tasks.py

@@ -321,6 +321,9 @@ class Waiting(plumpy.Waiting):
     """The waiting state for the `CalcJob` process."""
 
     def __init__(self, process, done_callback, msg=None, data=None):
+        """
+        :param :class:`~plumpy.base.state_machine.StateMachine` process: The process this state belongs to
+        """
         super().__init__(process, done_callback, msg, data)
         self._task = None
         self._killing = None

aiida/engine/processes/process_spec.py

@@ -65,10 +65,10 @@ def exit_code(self, status, label, message, invalidates_cache=False):
             raise ValueError('status should be a positive integer, received {}'.format(type(status)))
 
         if not isinstance(label, str):
-            raise TypeError('label should be of basestring type and not of {}'.format(type(label)))
+            raise TypeError('label should be of str type and not of {}'.format(type(label)))
 
         if not isinstance(message, str):
-            raise TypeError('message should be of basestring type and not of {}'.format(type(message)))
+            raise TypeError('message should be of str type and not of {}'.format(type(message)))
 
         if not isinstance(invalidates_cache, bool):
             raise TypeError('invalidates_cache should be of type bool and not of {}'.format(type(invalidates_cache)))

aiida/orm/implementation/logs.py

@@ -45,7 +45,7 @@ def loggername(self):
         The name of the logger that created this entry
 
         :return: The entry loggername
-        :rtype: basestring
+        :rtype: str
         """
 
     @abc.abstractproperty
@@ -54,7 +54,7 @@ def levelname(self):
         The name of the log level
 
         :return: The entry log level name
-        :rtype: basestring
+        :rtype: str
         """
 
     @abc.abstractproperty
@@ -72,7 +72,7 @@ def message(self):
         Get the message corresponding to the entry
 
         :return: The entry message
-        :rtype: basestring
+        :rtype: str
         """
 
     @abc.abstractproperty

aiida/orm/logs.py

@@ -40,7 +40,7 @@ def create_entry_from_record(record):
             Helper function to create a log entry from a record created as by the python logging library
 
             :param record: The record created by the logging module
-            :type record: :class:`logging.record`
+            :type record: :class:`logging.LogRecord`
 
             :return: An object implementing the log entry interface
             :rtype: :class:`aiida.orm.logs.Log`
@@ -139,16 +139,16 @@ def __init__(self, time, loggername, levelname, dbnode_id, message='', metadata=
         :type time: :class:`!datetime.datetime`
 
         :param loggername: name of logger
-        :type loggername: basestring
+        :type loggername: str
 
         :param levelname: name of log level
-        :type levelname: basestring
+        :type levelname: str
 
         :param dbnode_id: id of database node
         :type dbnode_id: int
 
         :param message: log message
-        :type message: basestring
+        :type message: str
 
         :param metadata: metadata
         :type metadata: dict
@@ -194,7 +194,7 @@ def loggername(self):
         The name of the logger that created this entry
 
         :return: The entry loggername
-        :rtype: basestring
+        :rtype: str
         """
         return self._backend_entity.loggername
 
@@ -204,7 +204,7 @@ def levelname(self):
         The name of the log level
 
         :return: The entry log level name
-        :rtype: basestring
+        :rtype: str
         """
         return self._backend_entity.levelname
 
@@ -224,7 +224,7 @@ def message(self):
         Get the message corresponding to the entry
 
         :return: The entry message
-        :rtype: basestring
+        :rtype: str
         """
         return self._backend_entity.message
 

aiida/orm/nodes/data/array/xy.py

@@ -43,10 +43,10 @@ class XyData(ArrayData):
     def _arrayandname_validator(self, array, name, units):
         """
         Validates that the array is an numpy.ndarray and that the name is
-        of type basestring. Raises InputValidationError if this not the case.
+        of type str. Raises InputValidationError if this not the case.
         """
         if not isinstance(name, str):
-            raise InputValidationError('The name must always be an instance of basestring.')
+            raise InputValidationError('The name must always be a str.')
 
         if not isinstance(array, np.ndarray):
             raise InputValidationError('The input array must always be a numpy array')
@@ -55,7 +55,7 @@ def _arrayandname_validator(self, array, name, units):
         except ValueError:
             raise InputValidationError('The input array must only contain floats')
         if not isinstance(units, str):
-            raise InputValidationError('The units must always be an instance of basestring.')
+            raise InputValidationError('The units must always be a str.')
 
     def set_x(self, x_array, x_name, x_units):
         """

docs/source/conf.py

@@ -49,7 +49,11 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.imgmath', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'IPython.sphinxext.ipython_console_highlighting', 'IPython.sphinxext.ipython_directive', 'sphinxcontrib.contentui', 'aiida.sphinxext']
+extensions = [
+    'sphinx.ext.intersphinx', 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.viewcode', 'sphinx.ext.coverage',
+    'sphinx.ext.imgmath', 'sphinx.ext.ifconfig', 'sphinx.ext.todo', 'IPython.sphinxext.ipython_console_highlighting',
+    'IPython.sphinxext.ipython_directive', 'sphinxcontrib.contentui', 'aiida.sphinxext'
+]
 ipython_mplbackend = ''
 
 todo_include_todos = True
@@ -115,6 +119,14 @@
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+intersphinx_mapping = {
+    'click': ('https://click.palletsprojects.com/', None),
+    'flask': ('http://flask.pocoo.org/docs/latest/', None),
+    'flask_restful': ('https://flask-restful.readthedocs.io/en/latest/', None),
+    'kiwipy': ('https://kiwipy.readthedocs.io/en/latest/', None),
+    'plumpy': ('https://plumpy.readthedocs.io/en/latest/', None),
+    'python': ('https://docs.python.org/3', None),
+}
 
 # -- Options for HTML output ---------------------------------------------------
 
@@ -361,17 +373,8 @@ def setup(app):
 # Allow duplicate toc entries.
 #epub_tocdup = True
 
-# otherwise, readthedocs.org uses their theme by default, so no need
-# to specify it
-
-
 # Warnings to ignore when using the -n (nitpicky) option
-# We should ignore any python built-in exception, for instance
-nitpick_ignore = [('py:class','Warning'), ('py:class', 'exceptions.Warning')]
-
-for line in open('nitpick-exceptions'):
-    if line.strip() == '' or line.startswith('#'):
-        continue
-    dtype, target = line.split(None, 1)
-    target = target.strip()
-    nitpick_ignore.append((dtype, target))
+with open('nitpick-exceptions', 'r') as handle:
+    nitpick_ignore = [
+        tuple(line.strip().split(None, 1)) for line in handle.readlines() if line.strip() and not line.startswith('#')
+    ]