Merge 2fbcd3a into 84a4fda

.gitignore

@@ -48,6 +48,7 @@ docs/api/
 docs/docs/
 docs/examples
 docs/sample_data
+docs/models/
 docs/modules/
 
 # Mac OS X

docs/Makefile

@@ -1,9 +1,9 @@
 # Minimal makefile for Sphinx documentation
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-AUTOSOURCEDIR = $(SOURCEDIR)/modules
-BUILDDIR      = _build
+SPHINXOPTS     ?= -j auto
+SPHINXBUILD    ?= sphinx-build
+SOURCEDIR      = .
+AUTOSOURCEDIRS = $(SOURCEDIR)/api $(SOURCEDIR)/models $(SOURCEDIR)/modules
+BUILDDIR       = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -14,7 +14,7 @@ help:
 all: clean clean-apidoc html
 
 clean-apidoc:
-	rm -rf "$(AUTOSOURCEDIR)"
+	rm -rf $(AUTOSOURCEDIRS)
 
 # Catch-all target: route all unknown targets to Sphinx builder
 %: Makefile

docs/_static/style.css → docs/_static/autofunction.css

@@ -18,4 +18,4 @@
 dt:target {
     margin-top: 0;
     padding-top: 0;
-}
+}

docs/_static/table.css

@@ -0,0 +1,30 @@
+/* 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
+}
+.docutils th {
+    min-width:5rem;
+    padding:.6rem .8rem;
+    background-color: #ecf0f3;
+    border-top: 3px solid #00bfa5;
+    vertical-align:top
+}
+.docutils td {
+    padding:.6rem .8rem;
+    border-top:.05rem solid rgba(0,1,0,.07);
+    vertical-align:top
+}
+.docutils tr{transition:background-color .125s}
+.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}

docs/_templates/autosummary_core/class.rst

@@ -0,0 +1,36 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+   :members:
+
+   {% block attributes_summary %}
+   {% if attributes %}
+   .. rubric:: Attributes Summary
+
+   .. csv-table::
+      :class: docutils
+      :header: "Name", "Type", "Description"
+      :widths: 10, 12, 30
+      :file: {{ '../models/' + objname + '.csv' }}
+
+   {% endif %}
+   {% endblock %}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: Methods
+
+   {% for item in methods %}
+   .. automethod:: {{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}

docs/_templates/autosummary_core/module.rst

@@ -0,0 +1,41 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. automodule:: {{ fullname }}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: Functions
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: Exceptions
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/module.rst_t

@@ -1,16 +1,12 @@
 {{- basename | e | heading }}
 
-{# ===== Show function summary (except for model package) =====}
-{# TODO: A better generic solution for this #}
-{%- if not qualname.startswith('pyinaturalist.models.') %}
 Summary
 ^^^^^^^
 .. automodsumm:: {{ qualname }}
    :functions-only:
 
 Details
 ^^^^^^^
-{%- endif %}
 .. automodule:: {{ qualname }}
 {%- for option in automodule_options %}
    :{{ option }}:

docs/_templates/package.rst_t

@@ -19,22 +19,8 @@
 {{- pkgname | e | heading }}
 {% endif %}
 
-{# ===== Class summary (models package only) =====}
-{# TODO: A better generic solution for this #}
-{%- if pkgname.endswith('.models') %}
-Classes
--------
-{% for submodule in submodules %}
-
-.. automodsumm:: {{ submodule }}
-    :classes-only:
-    :nosignatures:
-
-{% endfor %}
-{%- endif %}
-
-{# ===== Function summary (API function packages) ===== #}
-{%- if submodules and not pkgname.endswith('.models') %}
+{# ===== Function summary ===== #}
+{%- if submodules %}
 Functions
 ---------
 {% for submodule in submodules %}

docs/automodapi.rst

@@ -0,0 +1,3 @@
+.. This file exists only to generate sources.
+.. Then automodsumm is used to generate a table of classes only.
+.. automodapi:: pyinaturalist.models

docs/conf.py

@@ -2,7 +2,9 @@
 
 * ``forge`` is used to define and reuse documentation for API request parameters
 * ``apidoc`` is used to generate rst sources for **modules**
-* ``autosummary`` + ``automodapi`` to generate rst sources for **packages, classes, and summaries**
+* ``autosummary`` is used to generate rst sources for **packages and summaries**
+* ``automodapi`` + ``pyinaturalist.api_docs.model_docs`` are used to generate model
+  documentation based on ``attrs`` fields + metadata
 * ``intersphinx`` is used to insert links to other projects' docs
 * Jinja templates provide some additional customization:
     * Show a class summary for ``pyinaturalist.models`` package
@@ -15,13 +17,14 @@
   versions are listed in ``static/versions.json``
 
 TODO:
-
 * Customization for package-level docs that can be done with module docstrings instead of templates?
 * Automatically generate list of versions for version dropdown?
 """
+# flake8: noqa: E402
 import sys
+from glob import glob
 from os import makedirs, symlink
-from os.path import abspath, dirname, exists, join
+from os.path import abspath, basename, dirname, exists, join
 from shutil import copytree, rmtree
 
 
@@ -32,40 +35,40 @@
     pass
 
 DOCS_DIR = abspath(dirname(__file__))
+CSS_DIR = join(DOCS_DIR, '_static')
 MODULE_DOCS_DIR = join(DOCS_DIR, 'modules')
 PROJECT_DIR = dirname(DOCS_DIR)
 PACKAGE_DIR = join(PROJECT_DIR, 'pyinaturalist')
 
 # Source paths and symlink paths for static content to include
-IMAGE_DIR_SRC = join(DOCS_DIR, 'images')
-IMAGE_DIR_SYMLINK = join(DOCS_DIR, 'docs', 'images')
 DATA_DIR_SRC = join(PROJECT_DIR, 'test', 'sample_data')
 DATA_DIR_SYMLINK = join(DOCS_DIR, 'sample_data')
+IMAGE_DIR_SRC = join(DOCS_DIR, 'images')
+IMAGE_DIR_SYMLINK = join(DOCS_DIR, 'docs', 'images')
 NOTEBOOK_DIR_SRC = join(PROJECT_DIR, 'examples')
 NOTEBOOK_DIR_COPY = join(DOCS_DIR, 'examples')
 
 # Add project path so we can import our package
 sys.path.insert(0, PROJECT_DIR)
-from pyinaturalist import __version__  # noqa: E402
+from pyinaturalist import __version__
+from pyinaturalist.api_docs import document_models
 
 # General information about the project.
-project = 'pyinaturalist'
 copyright = '2021, Nicolas Noé, Jordan Cook'
-needs_sphinx = '4.0'
+exclude_patterns = ['_build', 'modules/pyinaturalist.rst']
+html_static_path = ['_static']
 master_doc = 'index'
+needs_sphinx = '4.0'
+project = 'pyinaturalist'
 source_suffix = ['.rst', '.md']
-version = release = __version__
-html_static_path = ['_static']
 templates_path = ['_templates']
-
-# Exclude the generated pyinaturalist.rst, which will just contain top-level __init__ info
-# and add an extra level to the toctree
-exclude_patterns = ['_build', 'modules/pyinaturalist.rst']
+version = release = __version__
 
 # Sphinx extension modules
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
+    'sphinx.ext.autosectionlabel',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx_autodoc_typehints',
@@ -86,33 +89,45 @@
     'requests': ('https://requests.readthedocs.io/en/master/', None),
 }
 
-# Enable Google-style docstrings
+# Generate labels in the format <page>:<section>
+autosectionlabel_prefix_document = True
+suppress_warnings = ['autosectionlabel.*']
+
+# napoleon settings
 napoleon_google_docstring = True
+napoleon_include_init_with_doc = True
 napoleon_include_private_with_doc = False
 napoleon_include_special_with_doc = False
+napoleon_use_param = True
+napoleon_type_aliases = {
+    'DateOrInt': 'pyinaturalist.constants.DateOrInt',
+    'IntOrStr': 'pyinaturalist.constants.IntOrStr',
+    'MultiInt': 'pyinaturalist.constants.MultiInt',
+    'MultiStr': 'pyinaturalist.constants.MultiStr',
+}
 
-# Strip prompt text when copying code blocks with copy button
+# copybutton settings: Strip prompt text when copying code blocks
 copybutton_prompt_text = r'>>> |\.\.\. |\$ '
 copybutton_prompt_is_regexp = True
 
 # Move type hint info to function description instead of signature
 autodoc_typehints = 'description'
-set_type_checking_flag = True
 
 # apidoc settings
 apidoc_module_dir = PACKAGE_DIR
 apidoc_output_dir = 'modules'
-apidoc_excluded_paths = ['api_docs/*', 'node_api.py', 'rest_api.py']
+apidoc_excluded_paths = ['api_docs/*', 'models/*', 'node_api.py', 'rest_api.py']
 apidoc_extra_args = ['--templatedir=_templates']
 apidoc_module_first = True
 apidoc_separate_modules = True
 apidoc_toc_file = False
 
 # autosummary + automodapi settings
 automodapi_inheritance_diagram = False
+automodapi_toctreedirnm = 'modules'
 automodsumm_inherited_members = False
 autosummary_generate = True
-autosummary_generate_overwrite = False
+autosummary_generate_overwrite = True
 autosummary_imported_members = False
 numpydoc_show_class_members = False
 
@@ -126,6 +141,7 @@
     'globaltoc_includehidden': False,
     'master_doc': False,
     'nav_title': project,
+    'table_classes': ['docutils'],
     'repo_url': 'https://github.com/niconoe/pyinaturalist',
     'repo_name': project,
     'version_dropdown': True,
@@ -154,10 +170,11 @@ def setup(app):
         * https://docs.readthedocs.io/en/stable/builds.html
         * https://github.com/sphinx-contrib/apidoc
     """
+    app.connect('builder-inited', document_models)
     app.connect('builder-inited', setup_external_files)
     app.connect('builder-inited', patch_automodapi)
-    app.add_css_file('style.css')
-    app.add_css_file('collapsible_container.css')
+    for stylesheet in glob(join(CSS_DIR, '*.css')):
+        app.add_css_file(basename(stylesheet))
 
 
 def setup_external_files(app):

docs/pyinaturalist.models.rst

@@ -0,0 +1,8 @@
+pyinaturalist.models
+====================
+.. automodule:: pyinaturalist.models
+
+.. automodsumm:: pyinaturalist.models
+    :classes-only:
+    :nosignatures:
+    :skip: BaseModel, BaseModelCollection, LazyProperty

docs/reference.rst

@@ -26,7 +26,7 @@ Also see :ref:`endpoints` for an overview of which iNaturalist endpoints are cur
     modules/pyinaturalist.v0
     modules/pyinaturalist.v1
     modules/pyinaturalist.v2
-    modules/pyinaturalist.models
+    pyinaturalist.models
 
 .. toctree::
     :caption: Additional Utility Modules

pyinaturalist/api_docs/__init__.py

@@ -1,8 +1,14 @@
 # flake8: noqa: F401, F403
+"""Utilities for generating pyinaturalist documentation, including:
+
+* Dynamic docs: Function signatures + docstrings based on API request params
+* Static docs: Sphinx documentation on readthedocs.io
+"""
 from pyinaturalist.api_docs.forge_utils import (
     copy_doc_signature,
     copy_docstrings,
     copy_signature,
     copy_signatures,
     document_request_params,
 )
+from pyinaturalist.api_docs.model_docs import document_models