Merge pull request #1016 from zitrosolrac/newDocApiSite

Doc API site

Author: guzman-raphael

.github/workflows/development.yaml

@@ -9,6 +9,23 @@ on:
       - '**' # every branch
       - '!stage*' # exclude branches beginning with stage
 jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    env:
+      DOCKER_CLIENT_TIMEOUT: "120"
+      COMPOSE_HTTP_TIMEOUT: "120"
+    steps:
+      - uses: actions/checkout@v2
+      - name: Compile docs static artifacts
+        run: |
+          export HOST_UID=$(id -u)
+          docker-compose -f ./docs-api/docker-compose.yaml up --exit-code-from docs-builder --build 
+      - name: Add docs static artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: docs-api-static
+          path: docs-api/build/html
+          retention-days: 1
   test:
     if: github.event_name == 'push' || github.event_name == 'pull_request'
     runs-on: ubuntu-latest
@@ -51,3 +68,41 @@ jobs:
                  --count --max-complexity=62 --max-line-length=127 --statistics
           black datajoint --check -v
           black tests --check -v
+  publish-docs:
+    if: |
+      github.event_name == 'push' &&
+      (
+        github.repository_owner == 'datajoint' ||
+        github.repository_owner == 'datajoint-company' ||
+        github.repository_owner == 'dj-sciops'
+      )
+    needs: build-docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Fetch docs static artifacts
+        uses: actions/download-artifact@v2
+        with:
+          name: docs-api-static
+          path: docs-api/build/html
+      - name: Commit documentation changes
+        run: |
+          git clone https://github.com/${GITHUB_REPOSITORY}.git \
+              --branch gh-pages --single-branch gh-pages
+          rm -R gh-pages/*
+          cp -r docs-api/build/html/* gh-pages/
+          cp .gitignore gh-pages/
+          touch gh-pages/.nojekyll
+          cd gh-pages
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git add . --all
+          git commit -m "Update documentation" -a || true
+          # The above command will fail if no changes were present, so we ignore
+          # the return code.
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        with:
+          branch: gh-pages
+          directory: gh-pages
+          github_token: ${{secrets.GITHUB_TOKEN}}

.nojekyll

@@ -28,6 +28,7 @@ def set_password(
 def kill(restriction=None, connection=None, order_by=None):  # pragma: no cover
     """
     view and kill database connections.
+
     :param restriction: restriction to be applied to processlist
     :param connection: a datajoint.Connection object. Default calls datajoint.conn()
     :param order_by: order by a single attribute or the list of attributes. defaults to 'id'.
@@ -86,6 +87,7 @@ def kill(restriction=None, connection=None, order_by=None):  # pragma: no cover
 def kill_quick(restriction=None, connection=None):
     """
     Kill database connections without prompting. Returns number of terminated connections.
+
     :param restriction: restriction to be applied to processlist
     :param connection: a datajoint.Connection object. Default calls datajoint.conn()
 

datajoint/admin.py

@@ -18,14 +18,17 @@ def attribute_type(self):
     def get(self, value):
         """
         convert value retrieved from the the attribute in a table into the adapted type
+
         :param value: value from the database
+
         :return: object of the adapted type
         """
         raise NotImplementedError("Undefined attribute adapter")
 
     def put(self, obj):
         """
         convert an object of the adapted type into a value that DataJoint can store in a table attribute
+
         :param obj: an object of the adapted type
         :return: value to store in the database
         """

datajoint/attribute_adapter.py

@@ -52,6 +52,7 @@ def connect_host_hook(connection_obj):
 def translate_query_error(client_error, query):
     """
     Take client error and original query and return the corresponding DataJoint exception.
+
     :param client_error: the exception raised by the client interface
     :param query: sql query with placeholders
     :return: an instance of the corresponding subclass of datajoint.errors.DataJointError
@@ -247,6 +248,7 @@ def set_query_cache(self, query_cache=None):
         1. Only SELECT queries are allowed.
         2. The results of queries are cached under the path indicated by dj.config['query_cache']
         3. query_cache is a string that differentiates different cache states.
+
         :param query_cache: a string to initialize the hash for query results
         """
         self._query_cache = query_cache
@@ -298,6 +300,7 @@ def query(
     ):
         """
         Execute the specified query and return the tuple generator (cursor).
+
         :param query: SQL query
         :param args: additional arguments for the client.cursor
         :param as_dict: If as_dict is set to True, the returned cursor objects returns

datajoint/connection.py

@@ -153,6 +153,7 @@ def build_index_parser():
 
 def is_foreign_key(line):
     """
+
     :param line: a line from the table definition
     :return: true if the line appears to be a foreign key definition
     """
@@ -366,6 +367,7 @@ def prepare_declare(definition, context):
 def declare(full_table_name, definition, context):
     """
     Parse declaration and generate the SQL CREATE TABLE code
+
     :param full_table_name: full name of the table
     :param definition: DataJoint table definition
     :param context: dictionary of objects that might be referred to in the table
@@ -566,6 +568,7 @@ def substitute_special_type(match, category, foreign_key_sql, context):
 def compile_attribute(line, in_key, foreign_key_sql, context):
     """
     Convert attribute definition from DataJoint format to SQL
+
     :param line: attribution line
     :param in_key: set to True if attribute is in primary key set
     :param foreign_key_sql: the list of foreign key declarations to add to

datajoint/declare.py

@@ -146,6 +146,7 @@ def __init__(self, source, context=None):
         def from_sequence(cls, sequence):
             """
             The join Diagram for all objects in sequence
+
             :param sequence: a sequence (e.g. list, tuple)
             :return: Diagram(arg1) + ... + Diagram(argn)
             """

datajoint/diagram.py

@@ -34,6 +34,7 @@ def __init__(self, *args):
     def suggest(self, *args):
         """
         regenerate the exception with additional arguments
+
         :param args: addition arguments
         :return: a new exception of the same type with the additional arguments
         """

datajoint/errors.py

@@ -121,6 +121,7 @@ def where_clause(self):
     def make_sql(self, fields=None):
         """
         Make the SQL SELECT statement.
+
         :param fields: used to explicitly set the select attributes
         """
         return "SELECT {distinct}{fields} FROM {from_}{where}".format(
@@ -323,6 +324,7 @@ def __add__(self, other):
     def proj(self, *attributes, **named_attributes):
         """
         Projection operator.
+
         :param attributes:  attributes to be included in the result. (The primary key is already included).
         :param named_attributes: new attributes computed or renamed from existing attributes.
         :return: the projected expression.
@@ -481,6 +483,7 @@ def aggr(self, group, *attributes, keep_all_rows=False, **named_attributes):
         """
         Aggregation of the type U('attr1','attr2').aggr(group, computation="QueryExpression")
         has the primary key ('attr1','attr2') and performs aggregation computations for all matching elements of `group`.
+
         :param group:  The query expression to be aggregated.
         :param keep_all_rows: True=keep all the rows from self. False=keep only rows that match entries in group.
         :param named_attributes: computations of the form new_attribute="sql expression on attributes of group"
@@ -510,6 +513,7 @@ def head(self, limit=25, **fetch_kwargs):
         """
         shortcut to fetch the first few entries from query expression.
         Equivalent to fetch(order_by="KEY", limit=25)
+
         :param limit:  number of entries
         :param fetch_kwargs: kwargs for fetch
         :return: query result
@@ -520,6 +524,7 @@ def tail(self, limit=25, **fetch_kwargs):
         """
         shortcut to fetch the last few entries from query expression.
         Equivalent to fetch(order_by="KEY DESC", limit=25)[::-1]
+
         :param limit:  number of entries
         :param fetch_kwargs: kwargs for fetch
         :return: query result
@@ -561,6 +566,7 @@ def __contains__(self, item):
         """
         returns True if the restriction in item matches any entries in self
             e.g. ``restriction in q1``.
+
         :param item: any restriction
         (item in query_expression) is equivalent to bool(query_expression & item) but may be
         executed more efficiently.
@@ -907,6 +913,7 @@ def aggr(self, group, **named_attributes):
         """
         Aggregation of the type U('attr1','attr2').aggr(group, computation="QueryExpression")
         has the primary key ('attr1','attr2') and performs aggregation computations for all matching elements of `group`.
+
         :param group:  The query expression to be aggregated.
         :param named_attributes: computations of the form new_attribute="sql expression on attributes of group"
         :return: The derived query expression

datajoint/expression.py

@@ -300,6 +300,7 @@ def upload_filepath(self, local_filepath):
     def download_filepath(self, filepath_hash):
         """
         sync a file from external store to the local stage
+
         :param filepath_hash: The hash (UUID) of the relative_path
         :return: hash (UUID) of the contents of the downloaded file or Nones
         """
@@ -351,6 +352,7 @@ def fetch_external_paths(self, **fetch_kwargs):
         """
         generate complete external filepaths from the query.
         Each element is a tuple: (uuid, path)
+
         :param fetch_kwargs: keyword arguments to pass to fetch
         """
         fetch_kwargs.update(as_dict=True)
@@ -371,6 +373,7 @@ def fetch_external_paths(self, **fetch_kwargs):
     def unused(self):
         """
         query expression for unused hashes
+
         :return: self restricted to elements that are not in use by any tables in the schema
         """
         return self - [
@@ -383,6 +386,7 @@ def unused(self):
     def used(self):
         """
         query expression for used hashes
+
         :return: self restricted to elements that in use by tables in the schema
         """
         return self & [
@@ -401,9 +405,9 @@ def delete(
         errors_as_string=True
     ):
         """
-        :param delete_external_files: True or False. If False, only the tracking info is removed from the
-        external store table but the external files remain intact. If True, then the external files
-        themselves are deleted too.
+
+        :param delete_external_files: True or False. If False, only the tracking info is removed from the external
+                store table but the external files remain intact. If True, then the external files themselves are deleted too.
         :param errors_as_string: If True any errors returned when deleting from external files will be strings
         :param limit: (integer) limit the number of items to delete
         :param display_progress: if True, display progress as files are cleaned up
@@ -470,6 +474,7 @@ def __getitem__(self, store):
         """
         Triggers the creation of an external table.
         Should only be used when ready to save or read from external storage.
+
         :param store: the name of the store
         :return: the ExternalTable object for the store
         """