From 96d4b404ce3322da8c21aa5cf450bb06a473d388 Mon Sep 17 00:00:00 2001 From: Jordan Cook Date: Sat, 3 Jul 2021 22:31:59 -0500 Subject: [PATCH 1/2] Indicate which attributes are properties in model attribute tables --- pyinaturalist/api_docs/model_docs.py | 13 ++++++++----- pyinaturalist/models/observation.py | 1 + 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/pyinaturalist/api_docs/model_docs.py b/pyinaturalist/api_docs/model_docs.py index c60b5b90..de2fbb8b 100644 --- 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 index 1b8c38bc..edada814 100644 --- 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 From 86a1f9e958927a1d7b9bcf26dd814d0671932033 Mon Sep 17 00:00:00 2001 From: Jordan Cook Date: Sat, 3 Jul 2021 22:35:20 -0500 Subject: [PATCH 2/2] Improve table formatting, and increase content width for model doc pages --- docs/_static/table.css | 54 ++++++++++++---------- docs/_templates/autosummary_core/class.rst | 7 ++- docs/conf.py | 7 +-- pyinaturalist/api_docs/forge_utils.py | 4 +- 4 files changed, 41 insertions(+), 31 deletions(-) diff --git a/docs/_static/table.css b/docs/_static/table.css index c9b33bed..119c035f 100644 --- 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} \ No newline at end of file + + +/* 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 index 20d9bb23..12f87a21 100644 --- 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 + + + .. 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 index 899be406..f18f7a8a 100644 --- 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 index b47f70e1..cb73f6ec 100644 --- 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"""