Merge pull request #526 from pyinat/docs

Documentation updates

.github/ISSUE_TEMPLATE/bug_report.md

@@ -20,5 +20,5 @@ _Is there an existing workaround for this issue?_
 
 ### Environment
  - OS & version: [e.g. Debian 10]
- - Python version: [e.g. `3.9`]
- - Pyinaturalist version or branch: [e.g. `0.13` or `main` branch]
+ - Python version: [e.g. `3.12`]
+ - Pyinaturalist version or branch: [e.g. `0.19` or `main` branch]

.github/ISSUE_TEMPLATE/question.md

@@ -1,7 +1,12 @@
 ---
 name: "\U00002754 Question"
-about: 'Question about how to use pyinaturalist'
+about: 'Question about pyinaturalist'
 title: ''
 labels: question
 
 ---
+
+<!--
+Note: For more open-ended questions, please create a new discussion:
+https://github.com/orgs/pyinat/discussions
+-->

.github/pull_request_template.md

@@ -1,12 +1,17 @@
 # New API Endpoint(s):
 Closes #<issue number>
 
+<!--
+If any of the items below don't apply to your PR, you can just remove them.
+See the contributing guide for more info:
+https://pyinaturalist.readthedocs.io/en/main/contributing.html
+-->
 ### Checklist
 * **Endpoint implementations**
   - [ ] e.g., `GET /observations`
 * **Docs**
   - [ ] (Optional) add a response formatting function to `pyinaturalist.formatters`
-  - [ ] Add doctrings + type annotations to `pyinaturalist.api_docs`
+  - [ ] Add doctrings + type annotations
   - [ ] Add usage example(s) to API function docstring
   - [ ] Update release notes in `HISTORY.md`
   - [ ] Verify that docs build correctly in Sphinx

HISTORY.md

@@ -4,6 +4,7 @@
 
 ### New Endpoints
 * Added new **User** endpoint: `get_current_user()`
+* Added new **Taxon** endpoint: `get_life_list_metadata()`
 
 ### Modified Endpoints
 Add support for searching observations by observation fields, using a new `observation_fields` param for the following functions:

README.md

@@ -1,6 +1,6 @@
 # pyinaturalist
 
-[![Build](https://github.com/pyinat/pyinaturalist/workflows/Build/badge.svg)](https://github.com/pyinat/pyinaturalist/actions)
+[![Build](https://github.com/pyinat/pyinaturalist/workflows/Build/badge.svg?branch=main)](https://github.com/pyinat/pyinaturalist/actions)
 [![Codecov](https://codecov.io/gh/pyinat/pyinaturalist/branch/main/graph/badge.svg)](https://codecov.io/gh/pyinat/pyinaturalist)
 [![Documentation](https://img.shields.io/readthedocs/pyinaturalist/stable)](https://pyinaturalist.readthedocs.io)
 
@@ -128,7 +128,7 @@ token = get_access_token(
     app_secret='my_app_secret',
 )
 ```
-See [Authentication](https://pyinaturalist.readthedocs.io/en/latest/user_guide.html#authentication)
+See [Authentication](https://pyinaturalist.readthedocs.io/en/stable/user_guide.html#authentication)
 for more options including environment variables, keyrings, and password managers.
 
 Now we can [create a new observation](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.create_observation):
@@ -183,23 +183,21 @@ As with observations, there is a lot of information in the response, but we'll p
 ## Next Steps
 For more information, see:
 
-* [User Guide](https://pyinaturalist.readthedocs.io/en/latest/user_guide.html):
+* [User Guide](https://pyinaturalist.readthedocs.io/en/stable/user_guide.html):
   introduction and general features that apply to most endpoints
-* [Endpoint Summary](https://pyinaturalist.readthedocs.io/en/latest/endpoints.html):
+* [Endpoint Summary](https://pyinaturalist.readthedocs.io/en/stable/endpoints.html):
   a complete list of endpoints wrapped by pyinaturalist
 * [Examples](https://pyinaturalist.readthedocs.io/en/stable/examples.html):
   data visualizations and other examples of things to do with iNaturalist data
-* [Reference](https://pyinaturalist.readthedocs.io/en/latest/reference.html): Detailed API documentation
+* [Reference](https://pyinaturalist.readthedocs.io/en/stable/reference.html): Detailed API documentation
 * [Contributing Guide](https://pyinaturalist.readthedocs.io/en/stable/contributing.html):
   development details for anyone interested in contributing to pyinaturalist
 * [History](https://github.com/pyinat/pyinaturalist/blob/dev/HISTORY.md):
   details on past and current releases
 * [Issues](https://github.com/pyinat/pyinaturalist/issues): planned & proposed features
 
 ## Feedback
-If you have any problems, suggestions, or questions about pyinaturalist, please let us know!
-Just [create an issue](https://github.com/pyinat/pyinaturalist/issues/new/choose).
-Also, **PRs are welcome!**
+If you have any problems, suggestions, or questions about pyinaturalist, you are welcome to [create an issue](https://github.com/pyinat/pyinaturalist/issues/new/choose) or [discussion](https://github.com/orgs/pyinat/discussions). Also, **PRs are welcome!**
 
 **Note:** pyinaturalist is developed by members of the iNaturalist community, and is not endorsed by
 iNaturalist.org or the California Academy of Sciences. If you have non-python-specific questions

docs/_templates/module.rst_t

@@ -2,6 +2,16 @@
 
 Summary
 ^^^^^^^
+{#
+   TODO: Include these sections only if classes/functions exist in the current module.
+   The automodule directive currently doesn't pass enough info into the template context
+   to make this possible.
+#}
+.. rubric:: Classes
+.. automodsumm:: {{ qualname }}
+   :classes-only:
+
+.. rubric:: Functions
 .. automodsumm:: {{ qualname }}
    :functions-only:
 

docs/conf.py

@@ -66,6 +66,7 @@
     'sphinx_copybutton',
     'sphinx_design',
     'sphinxcontrib.apidoc',
+    'sphinxext.opengraph',
     'myst_parser',
     'nbsphinx',
 ]
@@ -92,7 +93,7 @@
 # Enable automatic links to other projects' Sphinx docs
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
-    'requests': ('https://requests.readthedocs.io/en/master/', None),
+    'requests': ('https://requests.readthedocs.io/en/latest/', None),
     'requests_cache': ('https://requests-cache.readthedocs.io/en/stable/', None),
     'requests_ratelimiter': ('https://requests-ratelimiter.readthedocs.io/en/latest/', None),
     'urllib3': ('https://urllib3.readthedocs.io/en/stable/', None),
@@ -148,13 +149,17 @@
 autosummary_imported_members = False
 numpydoc_show_class_members = False
 
+# OpenGraph settings
+ogp_site_url = 'https://pyinaturalist.readthedocs.io'
+ogp_image = (
+    'https://raw.githubusercontent.com/pyinat/pyinaturalist/main/docs/images/python-logo-green.png'
+)
+
 # HTML general settings
 html_static_path = ['_static']
 html_favicon = join('_static', 'favicon.ico')
 html_logo = join('_static', 'pyinaturalist_logo.png')
-html_js_files = ['collapsible_container.js']
 html_css_files = [
-    'collapsible_container.css',
     'colors.css',
     'table.css',
     'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css',
@@ -190,6 +195,7 @@ def setup(app):
         * https://docs.readthedocs.io/en/stable/builds.html
         * https://github.com/sphinx-contrib/apidoc
     """
+    app.connect('config-inited', patch_sphinx_jinja_extensions)
     app.connect('builder-inited', document_models)
     app.connect('builder-inited', setup_external_files)
     app.connect('builder-inited', patch_automodapi)
@@ -211,6 +217,21 @@ def make_symlink(src, dest):
         symlink(src, dest)
 
 
+# TODO: Surely there's an easier way to do this?
+def patch_sphinx_jinja_extensions(*args):
+    """Monkey-patch Sphinx to enable Jinja extensions"""
+    from jinja2 import Environment
+    from sphinx.jinja2glue import SphinxFileSystemLoader
+
+    original_get_source = SphinxFileSystemLoader.get_source
+
+    def get_source(self, environment: Environment, template: str):
+        environment.add_extension('jinja2.ext.debug')
+        return original_get_source(self, environment, template)
+
+    SphinxFileSystemLoader.get_source = get_source
+
+
 def patch_automodapi(app):
     """Monkey-patch the automodapi extension to exclude imported members.
 

docs/endpoints.md

@@ -59,7 +59,7 @@ For all available endpoints, see: <http://api.inaturalist.org/v1/docs/>
 | GET    | /taxa/{id}                         | {py:func}`.get_taxa_by_id`                                   |
 | GET    | /taxa/{id}/map_layers              | {py:func}`.get_taxa_map_layers`                              |
 | GET    | /taxa/autocomplete                 | {py:func}`.get_taxa_autocomplete`                            |
-| GET    | /taxa/lifelist_metadata            | {py:func}`.get_lifelist_metadata`                            |
+| GET    | /taxa/lifelist_metadata            | {py:func}`.get_life_list_metadata`                           |
 | GET    | /users/{id}                        | {py:func}`.get_user_by_id`                                   |
 | GET    | /users/{id}/projects               |
 | GET    | /users/autocomplete                | {py:func}`.get_users_autocomplete`                           |

docs/examples.md

@@ -44,8 +44,7 @@ TODO: Can't generate thumbnails for Altair visualizations
     :end-line: 6
 ```
 
-:::{admonition} Example code
-:class: toggle
+:::{dropdown} Example code
 
 ```{literalinclude} ../examples/observations_to_gpx.py
 :lines: 1,8-
@@ -59,8 +58,7 @@ TODO: Can't generate thumbnails for Altair visualizations
     :end-line: 17
 ```
 
-:::{admonition} Example code
-:class: toggle
+:::{dropdown} Example code
 
 ```{literalinclude} ../examples/observation_photo_metadata.py
 :lines: 1,19-

docs/index.md

@@ -9,11 +9,15 @@
 ```{toctree}
 :maxdepth: 2
 
-user_guide
+user_guide/index
 examples
 endpoints
 reference
 contributing
 contributors
+```
+```{toctree}
+:maxdepth: 1
+
 history
 ```