Merge pull request #1055 from guzman-raphael/docs-styling

Update docs styling and update getting started

Author: dimitri-yatsenko

datajoint/table.py

@@ -22,6 +22,7 @@
     UnknownAttributeError,
     IntegrityError,
 )
+from typing import Union
 from .version import __version__ as version
 
 logger = logging.getLogger(__name__.split(".")[0])
@@ -459,15 +460,30 @@ def delete_quick(self, get_count=False):
         self._log(query[:255])
         return count
 
-    def delete(self, transaction=True, safemode=None, force_parts=False):
+    def delete(
+        self,
+        transaction: bool = True,
+        safemode: Union[bool, None] = None,
+        force_parts: bool = False,
+    ) -> int:
         """
         Deletes the contents of the table and its dependent tables, recursively.
 
-        :param transaction: if True, use the entire delete becomes an atomic transaction. This is the default and
-                            recommended behavior. Set to False if this delete is nested within another transaction.
-        :param safemode: If True, prohibit nested transactions and prompt to confirm. Default is dj.config['safemode'].
-        :param force_parts: Delete from parts even when not deleting from their masters.
-        :return: number of deleted rows (excluding those from dependent tables)
+        Args:
+            transaction: If `True`, use of the entire delete becomes an atomic transaction.
+                This is the default and recommended behavior. Set to `False` if this delete is
+                nested within another transaction.
+            safemode: If `True`, prohibit nested transactions and prompt to confirm. Default
+                is `dj.config['safemode']`.
+            force_parts: Delete from parts even when not deleting from their masters.
+
+        Returns:
+            Number of deleted rows (excluding those from dependent tables).
+
+        Raises:
+            DataJointError: Delete exceeds maximum number of delete attempts.
+            DataJointError: When deleting within an existing transaction.
+            DataJointError: Deleting a part table before its master.
         """
         deleted = set()
 

docs/mkdocs.yaml

@@ -4,8 +4,8 @@ site_name: DataJoint Python
 repo_url: https://github.com/datajoint/datajoint-python
 repo_name: datajoint/datajoint-python
 nav:
-  - DataJoint Python: getting_started.md
-  - Getting Started: getting_started.md
+  - DataJoint Python: getting_started/index.md
+  - Getting Started: getting_started/index.md
   - Concepts: concepts.md
   - Tutorials: tutorials.md
   - About:
@@ -17,9 +17,13 @@ nav:
 edit_uri: ./edit/master/docs/src
 docs_dir: ./src
 theme:
+  font:
+    text: Roboto Slab
+    code: Source Code Pro
   name: material
   custom_dir: src/.overrides
-  logo: assets/images/project-logo-black.png
+  icon:
+    logo: main/project-logo-black
   favicon: assets/images/project-logo-color.png
   features:
     - toc.integrate
@@ -38,9 +42,14 @@ plugins:
   - search
   - redirects:
       redirect_maps:
-        "index.md": "getting_started.md"
+        "index.md": "getting_started/index.md"
   - mkdocstrings:
       default_handler: python
+      handlers:
+        python:
+          selection:
+            filters:
+              - "!^_"
   - gen-files:
       scripts:
       - ./src/api/make_pages.py
@@ -54,10 +63,16 @@ markdown_extensions:
   - toc:
       permalink: true
   - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
       options:
         custom_icons:
           - .overrides/.icons
   - mdx_truly_sane_lists
+  - pymdownx.tabbed:
+      alternate_style: true
+  - admonition
+  - pymdownx.details
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
@@ -68,8 +83,10 @@ extra:
   version:
     provider: mike
   social:
-    - icon: datajoint/company-logo
+    - icon: main/company-logo
       link: https://www.datajoint.com/
+    - icon: fontawesome/solid/ticket
+      link: https://support.djneuro.io/portal/en/home
     - icon: fontawesome/brands/slack
       link: https://datajoint.slack.com
     - icon: fontawesome/brands/linkedin
@@ -78,6 +95,10 @@ extra:
       link: https://twitter.com/DataJointIO
     - icon: fontawesome/brands/github
       link: https://github.com/datajoint
+    - icon: fontawesome/brands/docker
+      link: https://hub.docker.com/u/datajoint
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/user/datajointbot
     - icon: fontawesome/brands/stack-overflow
       link: https://stackoverflow.com/questions/tagged/datajoint
     - icon: fontawesome/brands/youtube

docs/src/.overrides/.icons/datajoint/company-logo.svg

@@ -1,36 +1,59 @@
-[data-md-color-scheme="datajoint"] {
-
-    --dj-yellow: #fcb954;
-
-    --md-primary-fg-color: var(--dj-yellow);
-    --md-primary-bg-color: #000000;
-    --md-primary-fg-color--dark: var(--dj-yellow);
-
-    --md-accent-fg-color: var(--dj-yellow);
-
-    --md-code-bg-color: #e4f3f6;
+:root {
+    --dj-primary: #00a0df;
+    --dj-secondary: #ff5113;
+    --dj-background: #808285;
+    --dj-black: #000000;
+    --dj-white: #ffffff;
+}
 
-    --md-footer-fg-color: var(--dj-yellow);
+[data-md-color-scheme="datajoint"] {
+    /* ribbon */
+    /* ribbon + markdown heading expansion */
+    --md-primary-fg-color: var(--dj-black);
+    /* ribbon text */
+    --md-primary-bg-color: var(--dj-primary);
+
+    /* navigation */
+    /* navigation header + links */
+    --md-typeset-a-color: var(--dj-primary);
+    /* navigation on hover + diagram outline */
+    --md-accent-fg-color: var(--dj-secondary);
+
+    /* main */
+    /* main header + already viewed*/
+    --md-default-fg-color--light: var(--dj-background);
+    /* primary text */
+    --md-typeset-color: var(--dj-black);
+    /* code comments + diagram text */
+    --md-code-fg-color: var(--dj-secondary);
+
+    /* footer */
+    /* previous/next text */
+    --md-footer-fg-color: var(--dj-primary);
 }
 
 [data-md-color-scheme="slate"] {
-
-    --dj-yellow: #fcb954;
-
-    --md-typeset-color: #e4f3f6;
-    --md-typeset-a-color: #17b2ff;
-
-    --md-default-fg-color: #e4f3f6;
-    --md-default-fg-color--light: var(--dj-yellow);
-
-    --md-primary-fg-color: var(--dj-yellow);
-    --md-primary-bg-color: #000000;
-    --md-primary-fg-color--dark: var(--dj-yellow);
-
-    --md-accent-fg-color: var(--dj-yellow);
-
-    --md-code-fg-color: #76c9e9;
-    --md-code-hl-comment-color: #ffd28d;
-
-    --md-footer-fg-color: var(--dj-yellow);
+    /* ribbon */
+    /* ribbon + markdown heading expansion */
+    --md-primary-fg-color: var(--dj-primary);
+    /* ribbon text */
+    --md-primary-bg-color: var(--dj-white);
+
+    /* navigation */
+    /* navigation header + links */
+    --md-typeset-a-color: var(--dj-primary);
+    /* navigation on hover + diagram outline */
+    --md-accent-fg-color: var(--dj-secondary);
+
+    /* main */
+    /* main header + already viewed*/
+    --md-default-fg-color--light: var(--dj-background);
+    /* primary text */
+    --md-typeset-color: var(--dj-white);
+    /* code comments + diagram text */
+    --md-code-fg-color: var(--dj-secondary);
+
+    /* footer */
+    /* previous/next text */
+    --md-footer-fg-color: var(--dj-white);
 }