Merge branch 'style'

pyinat · Jul 4, 2021 · 7535063 · 7535063
2 parents 030f772 + 86a1f9e
commit 7535063
Show file tree

Hide file tree

Showing 6 changed files with 50 additions and 36 deletions.
diff --git a/docs/_static/table.css b/docs/_static/table.css
@@ -1,30 +1,36 @@
-/* Styles for tables. For sphinx-material, requires docutils class to be in 'table_classes' */
-.docutils table {
-    box-shadow:0 2px 2px 0 rgba(0,0,0,.14),0 1px 5px 0 rgba(0,0,0,.12),0 3px 1px -2px rgba(0,0,0,.2);
-    display:inline-block;
-    border-radius:.1rem;
-    font-size:.64rem;
-    margin-top:1.5em;
-    max-width:100%;
-    overflow:auto;
-    -webkit-overflow-scrolling:touch
+/* Slightly modified table styles from Furo theme*/
+
+table.docutils {
+  border-radius: 0.2rem;
+  border-spacing: 0;
+  border-collapse: collapse;
+  box-shadow:0 2px 2px 0 rgba(0,0,0,.14),0 1px 5px 0 rgba(0,0,0,.12),0 3px 1px -2px rgba(0,0,0,.2);
 }
-.docutils th {
-    min-width:5rem;
-    padding:.6rem .8rem;
-    background-color: #ecf0f3;
-    border-top: 3px solid #00bfa5;
-    vertical-align:top
+
+table.docutils th {
+    background: #63ccff;
+    border-bottom: 3px solid #006db3;
 }
-.docutils td {
-    padding:.6rem .8rem;
-    border-top:.05rem solid rgba(0,1,0,.07);
-    vertical-align:top
+
+/* TODO: Use variables for light/med/dark variants */
+@media (prefers-color-scheme: dark) {
+    table.docutils th {
+        background: #006db3;
+        border-bottom: 3px solid #63ccff;
+    }
+
 }
-.docutils tr{transition:background-color .125s}
-.docutils tr:hover{
+
+table.docutils tr{transition:background-color .125s}
+table.docutils tr:hover{
     background-color:rgba(0,0,0,.035);
     box-shadow:inset 0 .05rem 0 #fff
 }
-.docutils tr:first-child td{border-top:0}
-.docutils table a {word-break:normal}
+
+
+/* table.docutils td, th {
+    padding: 0 0.25rem;
+    border-left: 1px solid var(--color-background-border);
+    border-right: 1px solid var(--color-background-border);
+    border-bottom: 1px solid var(--color-background-border);
+} */
diff --git a/docs/_templates/autosummary_core/class.rst b/docs/_templates/autosummary_core/class.rst
@@ -3,6 +3,11 @@
 {{ objname }}
 {{ underline }}
 
+{# Increase the max content width, since we won't have a local ToC to the right #}
+.. raw:: html
+
+   <style>div.content{width: 60em}</style>
+
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
@@ -15,7 +20,7 @@
    .. csv-table::
       :class: docutils
       :header: "Name", "Type", "Description"
-      :widths: 10, 12, 30
+      :widths: 12 12 76
       :file: {{ '../models/' + objname + '.csv' }}
 
    {% endif %}

diff --git a/docs/conf.py b/docs/conf.py
@@ -147,11 +147,12 @@
 html_theme = 'furo'
 html_theme_options = {
     'light_css_variables': {
-        'color-brand-primary': '#436500',  # Dark green
-        # 'color-brand-content': 'teal',
+        'color-brand-primary': '#00766c',  # MD light-blue-600; light #64d8cb | med #26a69a
+        'color-brand-content': '#006db3',  # MD teal-400;       light #63ccff | med #039be5
     },
     'dark_css_variables': {
-        'color-brand-primary': '#74AC00',  # Yellow-green
+        'color-brand-primary': '#64d8cb',
+        'color-brand-content': '#63ccff',
     },
     'sidebar_hide_name': True,
 }

diff --git a/pyinaturalist/api_docs/forge_utils.py b/pyinaturalist/api_docs/forge_utils.py
@@ -5,7 +5,7 @@
 """
 from inspect import cleandoc, ismethod, signature
 from logging import getLogger
-from typing import Callable, List
+from typing import Callable, List, get_type_hints
 
 from requests import Session
 
@@ -72,8 +72,6 @@ def wrapper(func):
 # Alias specifically for API functions
 document_request_params = copy_doc_signature
 
-from typing import get_type_hints
-
 
 def copy_annotations(target_function: Callable, template_functions: List[TemplateFunction]) -> Callable:
     """Copy type annotations from one or more template functions to a target function"""

diff --git a/pyinaturalist/api_docs/model_docs.py b/pyinaturalist/api_docs/model_docs.py
@@ -15,6 +15,8 @@
 
 IGNORE_PROPERTIES = ['row']
 MODEL_DOC_DIR = join(DOCS_DIR, 'models')
+PROPERTY_TYPE = format_annotation(property)
+LAZY_PROPERTY_TYPE = format_annotation(LazyProperty)
 
 
 def document_models(app):
@@ -46,9 +48,9 @@ def get_model_doc(cls: Type) -> List[Tuple[str, str, str]]:
     """
 
     doc_rows = [_get_field_doc(field) for field in cls.__attrs_attrs__ if not field.name.startswith('_')]
-    doc_rows += [('', '', ''), ('', '', '')]
+    doc_rows += [('', '', '')]
     doc_rows += [_get_property_doc(prop) for prop in get_properties(cls)]
-    doc_rows += [('', '', ''), ('', '', '')]
+    doc_rows += [('', '', '')]
     doc_rows += [_get_lazy_property_doc(prop) for _, prop in get_lazy_properties(cls).items()]
     return doc_rows
 
@@ -76,15 +78,16 @@ def _get_field_doc(field: Attribute) -> Tuple[str, str, str]:
 
 def _get_property_doc(prop: property) -> Tuple[str, str, str]:
     """Get a row documenting a regular @property"""
-    rtype = format_annotation(get_type_hints(prop.fget).get('return', Any))
+    fget_rtype = get_type_hints(prop.fget).get('return', Any)
+    rtype = format_annotation(fget_rtype)
     doc = (prop.fget.__doc__ or '').split('\n')[0]
-    return (f'**{prop.fget.__name__}**', rtype, doc)
+    return (f'**{prop.fget.__name__}** ({PROPERTY_TYPE})', rtype, doc)
 
 
 def _get_lazy_property_doc(prop: LazyProperty) -> Tuple[str, str, str]:
     """Get a row documenting a LazyProperty"""
     rtype = format_annotation(prop.type)
-    return (f'**{prop.__name__}**', rtype, prop.__doc__)
+    return (f'**{prop.__name__}** ({LAZY_PROPERTY_TYPE})', rtype, prop.__doc__)
 
 
 def export_model_doc(model_name, doc_table):

diff --git a/pyinaturalist/models/observation.py b/pyinaturalist/models/observation.py
@@ -205,6 +205,7 @@ def from_id(cls, id: int):
 
     @property
     def thumbnail_url(self) -> Optional[str]:
+        """Thumbnail URL for first observation photo (if any)"""
         if not self.photos:
             return None
         return self.photos[0].thumbnail_url