Merge pull request #1330 from ltalirz/issue_1242_sphinx-apidoc_rebased

Generate complete API docs using sphinx-apidoc

.travis-data/test_script.sh

@@ -5,9 +5,11 @@ set -ev
 
 case "$TEST_TYPE" in
     docs)
-        # Compile the docs (HTML format); -W to convert warnings in errors, 
+        # Compile the docs (HTML format); 
+        # -C change to 'docs' directory before doing anything
         # -n to warn about all missing references
-        SPHINXOPTS="-nW" make -C docs html
+        # -W to convert warnings in errors
+        SPHINXOPTS="-nW" make -C docs
         ;;
     tests)
         # Add the .travis-data folder to the python path such that defined workchains can be found by the daemon

CHANGELOG.md

@@ -1,3 +1,8 @@
+# v0.11.3
+
+- Remove QueryTool (was deprecated in favor of QueryBuilder since v0.8.0)
+
+
 ## v0.11.2:
 
 ### Critical bug fixes

aiida/backends/djsite/cmdline.py

@@ -44,6 +44,7 @@ def get_workflow_list(pk_list=tuple(), user=None, all_states=False,
                       n_days_ago=None):
     """
     Get a list of workflow.
+
     :param user: A ORM User class if you want to filter by user
     :param pk_list: Limit the results to this list of PKs
     :param all_states: if False, limit results to "active" (e.g., running) wfs

aiida/backends/djsite/db/models.py

@@ -13,14 +13,14 @@
 from django.db import models as m
 from django_extensions.db.fields import UUIDField
 from django.contrib.auth.models import (
-    AbstractBaseUser, BaseUserManager, PermissionsMixin)
+    AbstractBaseUser, BaseUserManager, PermissionsMixin )
 from django.utils.encoding import python_2_unicode_compatible
 from django.core.exceptions import ObjectDoesNotExist
 from django.db.models.query import QuerySet
 
 from aiida.utils import timezone
 from aiida.common.exceptions import (
-    ConfigurationError, DbContentError, MissingPluginError)
+    ConfigurationError, DbContentError, MissingPluginError )
 
 from aiida.backends.settings import AIIDANODES_UUID_VERSION
 from aiida.backends.djsite.settings.settings import AUTH_USER_MODEL
@@ -319,10 +319,10 @@ def _deserialize_attribute(mainitem, subitems, sep, original_class=None,
     :param subitems: must be a dictionary of dictionaries. In the top-level dictionary,
       the key must be the key of the attribute, stripped of all prefixes
       (i.e., if the mainitem has key 'a.b' and we pass subitems
-        'a.b.0', 'a.b.1', 'a.b.1.c', their keys must be '0', '1', '1.c').
-        It must be None if the value is not iterable (int, str,
-        float, ...).
-        It is an empty dictionary if there are no subitems.
+      'a.b.0', 'a.b.1', 'a.b.1.c', their keys must be '0', '1', '1.c').
+      It must be None if the value is not iterable (int, str,
+      float, ...).
+      It is an empty dictionary if there are no subitems.
     :param sep: a string, the separator between subfields (to separate the
       name of a dictionary from the keys it contains, for instance)
     :param original_class: if these elements come from a specific subclass
@@ -341,7 +341,7 @@ def _deserialize_attribute(mainitem, subitems, sep, original_class=None,
       from the number declared in the ival field).
 
     :return: the deserialized value
-    :raise DeserializationError: if an error occurs
+    :raise aiida.backends.djsite.db.models.DeserializationException: if an error occurs
     """
     from aiida.utils.timezone import (
         is_naive, make_aware, get_current_timezone)
@@ -1380,7 +1380,7 @@ def get_dbcomputer(cls, computer):
         """
         Return a DbComputer from its name (or from another Computer or DbComputer instance)
         """
-        from django.core.exceptions import ObjectDoesNotExist, MultipleObjectsReturned
+        from django.core.exceptions import MultipleObjectsReturned
         from aiida.common.exceptions import NotExistent
         from aiida.orm.computer import Computer
 
@@ -1604,7 +1604,7 @@ class DbWorkflow(m.Model):
 
     def get_aiida_class(self):
         """
-        Return the corresponding aiida instance of class aiida.worflow
+        Return the corresponding aiida instance of class aiida.workflow
         """
         from aiida.orm.workflow import Workflow
 

aiida/backends/djsite/queries.py

@@ -23,8 +23,9 @@ def query_jobcalculations_by_computer_user_state(
 
         Issue a warning if the state is not in the list of valid states.
 
-        :param string state: The state to be used to filter (should be a string among
+        :param state: The state to be used to filter (should be a string among
                 those defined in aiida.common.datastructures.calc_states)
+        :type state: str
         :param computer: a Django DbComputer entry, or a Computer object, of a
                 computer in the DbComputer table.
                 A string for the hostname is also valid.
@@ -299,23 +300,25 @@ def get_all_parents(self, node_pks, return_values=['id']):
 def get_closest_parents(pks,*args,**kwargs):
     """
     Get the closest parents dbnodes of a set of nodes.
+
     :param pks: one pk or an iterable of pks of nodes
     :param chunk_size: we chunk the pks into groups of this size,
         to optimize the speed (default=50)
     :param print_progress: print the the progression if True (default=False).
-    :param args & kwargs: additional query parameters
-    :return: a dictionary of the form:
-        {pk1: pk of closest parent of node with pk1,
-         pk2: pk of closest parent of node with pk2,
-         etc.
-         }
+    :param args: additional query parameters
+    :param kwargs: additional query parameters
+    :returns: a dictionary of the form
+        pk1: pk of closest parent of node with pk1,
+        pk2: pk of closest parent of node with pk2
+
     .. note:: It works also if pks is a list of nodes rather than their pks
 
     .. todo:: find a way to always get a parent (when there is one) from each pk.
         Now, when the same parent has several children in pks, only
         one of them is kept. This is a BUG, related to the use of a dictionary
         (children_dict, see below...).
         For now a work around is to use chunk_size=1.
+
     """
     from aiida.orm import Node
     from aiida.backends.djsite.db import models

aiida/backends/djsite/settings/settings.py

@@ -72,7 +72,7 @@
 # Note: this variable might disappear in the future
 REPOSITORY_PROTOCOL, REPOSITORY_PATH = parse_repository_uri(REPOSITORY_URI)
 
-if settings.IN_DOC_MODE:
+if settings.IN_RT_DOC_MODE:
     pass
 elif REPOSITORY_PROTOCOL == 'file':
     if not os.path.isdir(REPOSITORY_PATH):

aiida/backends/djsite/utils.py

@@ -30,6 +30,7 @@ def load_dbenv(process=None, profile=None):
 def _load_dbenv_noschemacheck(process, profile):
     """
     Load the database environment (Django) WITHOUT CHECKING THE SCHEMA VERSION.
+
     :param process: the process that is calling this command ('verdi', or
         'daemon')
     :param profile: the string with the profile to use. If not specified,

aiida/backends/general/abstractqueries.py

@@ -30,22 +30,25 @@ def query_jobcalculations_by_computer_user_state(
 
         Issue a warning if the state is not in the list of valid states.
 
-        :param string state: The state to be used to filter (should be a string among
+        :param state: The state to be used to filter (should be a string among
                 those defined in aiida.common.datastructures.calc_states)
+        :type state: str
         :param computer: a Django DbComputer entry, or a Computer object, of a
                 computer in the DbComputer table.
                 A string for the hostname is also valid.
         :param user: a Django entry (or its pk) of a user in the DbUser table;
                 if present, the results are restricted to calculations of that
                 specific user
-        :param bool only_computer_user_pairs: if False (default) return a queryset
+        :param only_computer_user_pairs: if False (default) return a queryset
                 where each element is a suitable instance of Node (it should
                 be an instance of Calculation, if everything goes right!)
                 If True, return only a list of tuples, where each tuple is
                 in the format
                 ('dbcomputer__id', 'user__id')
                 [where the IDs are the IDs of the respective tables]
-        :param int limit: Limit the number of rows returned
+        :type only_computer_user_pairs: bool
+        :param limit: Limit the number of rows returned
+        :type limit: int
 
         :return: a list of calculation objects matching the filters.
         """

aiida/backends/settings.py

@@ -21,6 +21,10 @@
 
 # This is used (and should be set to true) for the correct compilation
 # of the documentation on readthedocs
+IN_RT_DOC_MODE = False
+
+# This is same as the trigger above, but is switched on for RTD documentation
+# compilation but also for local documentation compilation.
 IN_DOC_MODE = False
 
 # The following is a dummy config.json configuration that it is used for the

aiida/backends/sqlalchemy/cmdline.py

@@ -20,12 +20,13 @@ def get_group_list(user, type_string, n_days_ago=None,
 def get_workflow_list(pk_list=tuple(), user=None, all_states=False, 
                       n_days_ago=None):
     """
-    Get a list of workflow.
+    Get a list of workflow
+
     :param user: A ORM User class if you want to filter by user
     :param pk_list: Limit the results to this list of PKs
     :param all_states: if False, limit results to "active" (e.g., running) wfs
     :param n_days_ago: an integer number of days. If specifies, limit results to
-      workflows started up to this number of days ago
+        workflows started up to this number of days ago
     """
     from aiida.orm.workflow import Workflow
     from aiida.backends.sqlalchemy.models.workflow import DbWorkflow

aiida/backends/sqlalchemy/migrations/env.py

@@ -9,10 +9,7 @@
 ###########################################################################
 from __future__ import with_statement
 from alembic import context
-
-# this is the Alembic Config object, which provides
-# access to the values within the .ini file in use.
-config = context.config
+from aiida.backends.settings import IN_DOC_MODE
 
 # The available SQLAlchemy tables
 from aiida.backends.sqlalchemy.models.authinfo import DbAuthInfo
@@ -53,6 +50,12 @@ def run_migrations_online():
     and associate a connection with the context.
 
     """
+    # This is the Alembic Config object, which provides
+    # access to the values within the .ini file in use.
+    # It is initialized by alembic and we enrich it here
+    # to point to the right database configuration.
+    config = context.config
+
     connectable = config.attributes.get('connection', None)
 
     if connectable is None:
@@ -69,7 +72,8 @@ def run_migrations_online():
         with context.begin_transaction():
             context.run_migrations()
 
-if context.is_offline_mode():
-    run_migrations_offline()
-else:
-    run_migrations_online()
+if not IN_DOC_MODE:
+    if context.is_offline_mode():
+        run_migrations_offline()
+    else:
+        run_migrations_online()

aiida/backends/sqlalchemy/models/base.py

@@ -48,7 +48,8 @@ def __get__(self, obj, _type):
 class _AiidaQuery(orm.Query):
 
     def __init__(self, *args, **kwargs):
-            super(_AiidaQuery, self).__init__(*args, **kwargs)
+        """Constructor"""
+        super(_AiidaQuery, self).__init__(*args, **kwargs)
 
     def __iter__(self):
         iterator = super(_AiidaQuery, self).__iter__()

aiida/backends/sqlalchemy/tests/migrations.py

@@ -82,11 +82,14 @@ def migrate_db_with_non_testing_migrations(self, destination):
     def test_migrations_forward_backward(self):
         """
         This is a very broad test that checks that the migration mechanism
-        works. More specifically, it checks that:
-        - Alembic database migrations to specific versions work (upgrade &
-          downgrade)
-        - The methods that are checking the database schema version and perform
-          the migration procedure to the last version work correctly.
+        works. More specifically, it checks that::
+
+            - Alembic database migrations to specific versions work (upgrade &
+              downgrade)
+
+            - The methods that are checking the database schema version and perform
+              the migration procedure to the last version work correctly.
+
         """
         from aiida.backends.sqlalchemy.tests.migration_test import versions
         from aiida.backends.sqlalchemy.utils import check_schema_version

aiida/backends/sqlalchemy/utils.py

@@ -419,6 +419,13 @@ def check_schema_version(force_migration=False, alembic_cfg=None):
     import sys
     from aiida.common.utils import query_yes_no
     from aiida.backends import sqlalchemy as sa
+    from aiida.backends.settings import IN_DOC_MODE
+
+    # Early exit if we compile the documentation since the schema
+    # check is not needed and it creates problems with the sqlalchemy
+    # migrations
+    if IN_DOC_MODE:
+        return
 
     # If an alembic configuration file is given then use that one.
     if alembic_cfg is None:
@@ -467,6 +474,9 @@ def get_db_schema_version(config):
     :param config: The alembic configuration.
     :return: The version of the database.
     """
+    if config is None:
+        return None
+
     script = ScriptDirectory.from_config(config)
 
     def get_db_version(rev, _):