Merge pull request #1018 from guzman-raphael/api-docs-structure

Minor navigation experience improvements to API docs

Author: dimitri-yatsenko

datajoint/__init__.py

@@ -10,8 +10,9 @@
 that any use of DataJoint leading to a publication be acknowledged in the publication.
 
 Please cite:
-    http://biorxiv.org/content/early/2015/11/14/031658
-    http://dx.doi.org/10.1101/031658
+
+  - http://biorxiv.org/content/early/2015/11/14/031658
+  - http://dx.doi.org/10.1101/031658
 """
 
 __author__ = "DataJoint Contributors"

datajoint/connection.py

@@ -1,6 +1,6 @@
 """
-This module contains the Connection class that manages the connection to the database,
- and the `conn` function that provides access to a persistent connection in datajoint.
+This module contains the Connection class that manages the connection to the database, and
+the ``conn`` function that provides access to a persistent connection in datajoint.
 """
 import warnings
 from contextlib import contextmanager
@@ -109,11 +109,9 @@ def conn(
     :param password: mysql password
     :param init_fun: initialization function
     :param reset: whether the connection should be reset or not
-    :param use_tls: TLS encryption option. Valid options are: True (required),
-                    False (required no TLS), None (TLS prefered, default),
-                    dict (Manually specify values per
-                    https://dev.mysql.com/doc/refman/5.7/en/connection-options.html
-                        #encrypted-connection-options).
+    :param use_tls: TLS encryption option. Valid options are: True (required), False
+        (required no TLS), None (TLS prefered, default), dict (Manually specify values per
+        https://dev.mysql.com/doc/refman/5.7/en/connection-options.html#encrypted-connection-options).
     """
     if not hasattr(conn, "connection") or reset:
         host = host if host is not None else config["database.host"]

datajoint/table.py

@@ -276,16 +276,20 @@ def external(self):
 
     def update1(self, row):
         """
-        update1 updates one existing entry in the table.
-        Caution: In DataJoint the primary modes for data manipulation is to ``insert`` and ``delete``
-        entire records since referential integrity works on the level of records, not fields.
-        Therefore, updates are reserved for corrective operations outside of main workflow.
-        Use UPDATE methods sparingly with full awareness of potential violations of assumptions.
+        ``update1`` updates one existing entry in the table.
+        Caution: In DataJoint the primary modes for data manipulation is to ``insert`` and
+        ``delete`` entire records since referential integrity works on the level of records,
+        not fields. Therefore, updates are reserved for corrective operations outside of main
+        workflow. Use UPDATE methods sparingly with full awareness of potential violations of
+        assumptions.
 
         :param row: a ``dict`` containing the primary key values and the attributes to update.
-        Setting an attribute value to None will reset it to the default value (if any)
+            Setting an attribute value to None will reset it to the default value (if any).
+
         The primary key attributes must always be provided.
+
         Examples:
+
         >>> table.update1({'id': 1, 'value': 3})  # update value in record with id=1
         >>> table.update1({'id': 1, 'value': None})  # reset value to default
         """
@@ -326,7 +330,7 @@ def insert1(self, row, **kwargs):
         Insert one data record into the table. For ``kwargs``, see ``insert()``.
 
         :param row: a numpy record, a dict-like object, or an ordered sequence to be inserted
-        as one row.
+            as one row.
         """
         self.insert((row,), **kwargs)
 
@@ -339,16 +343,18 @@ def insert(
         allow_direct_insert=None,
     ):
         """
-            Insert a collection of rows.
-
-            :param rows: An iterable where an element is a numpy record, a dict-like object, a pandas.DataFrame, a sequence,
-                        or a query expression with the same heading as self.
-            :param replace: If True, replaces the existing tuple.
-            :param skip_duplicates: If True, silently skip duplicate inserts.
-            :param ignore_extra_fields: If False, fields that are not in the heading raise error.
-            :param allow_direct_insert: applies only in auto-populated tables.
-        If False (default), insert are allowed only from inside the make callback.
-            Example::
+        Insert a collection of rows.
+
+        :param rows: An iterable where an element is a numpy record, a dict-like object, a
+            pandas.DataFrame, a sequence, or a query expression with the same heading as self.
+        :param replace: If True, replaces the existing tuple.
+        :param skip_duplicates: If True, silently skip duplicate inserts.
+        :param ignore_extra_fields: If False, fields that are not in the heading raise error.
+        :param allow_direct_insert: applies only in auto-populated tables. If False (default),
+            insert are allowed only from inside the make callback.
+
+        Example:
+
             >>> relation.insert([
             >>>     dict(subject_id=7, species="mouse", date_of_birth="2014-09-01"),
             >>>     dict(subject_id=8, species="mouse", date_of_birth="2014-09-02")])

docs-api/docker-compose.yaml

@@ -1,4 +1,5 @@
 # HOST_UID=1000 docker-compose -f ./docs-api/docker-compose.yaml up --build
+# docker exec -it docs-api_docs-builder_1 bash -c "pip install -U /main/datajoint-python && rm -R build && make html"
 version: '2.4'
 services:
   # example how to build

docs-api/source/index.rst

@@ -6,13 +6,19 @@
 Welcome to DataJoint's API Documentation!
 =========================================
 
+datajoint module
+----------------
+
+.. automodule:: datajoint
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Submodules:
 
-   datajoint
-
-
+   submodules
 
 Indices and tables
 ==================

docs-api/source/datajoint.rst renamed to docs-api/source/submodules.rst

@@ -1,9 +1,3 @@
-datajoint package
-=================
-
-Submodules
-----------
-
 datajoint.admin module
 ----------------------
 
@@ -211,11 +205,3 @@ datajoint.version module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: datajoint
-   :members:
-   :undoc-members:
-   :show-inheritance: