docs: fix docstring formatting, other tweaks

admin.py

@@ -1,6 +1,6 @@
 """Renders admin pages for ops and other management tasks.
 
-Currently just /admin/responses, which shows active responses with tasks that
+Currently just ``/admin/responses``, which shows active responses with tasks that
 haven't completed yet.
 """
 import datetime

blog_webmention.py

@@ -1,5 +1,4 @@
-"""Converts webmentions to comments on Blogger, Tumblr, and WP.com.
-"""
+"""Converts webmentions to comments on Blogger, Tumblr, and WP.com."""
 import logging
 import urllib.parse
 
@@ -158,10 +157,10 @@ def find_mention_item(self, items):
     content.value.
 
     Args:
-      items: sequence of mf2 item dicts
+      items (list of dict): mf2 items
 
     Returns:
-      mf2 item dict or None
+      dict: mf2 item, or None
     """
     # find target URL in source
     for item in items:

blogger.py

@@ -7,18 +7,17 @@
 http://gdata-python-client.googlecode.com/hg/pydocs/gdata.blogger.data.html
 
 To use, go to your Blogger blog's dashboard, click Template, Edit HTML, then
-put this in the head section:
+put this in the head section::
 
-<link rel="webmention" href="https://brid.gy/webmention/blogger"></link>
+    <link rel="webmention" href="https://brid.gy/webmention/blogger"></link>
 
-https://developers.google.com/blogger/docs/2.0/developers_guide_protocol
-https://support.google.com/blogger/answer/42064?hl=en
-create comment:
-https://developers.google.com/blogger/docs/2.0/developers_guide_protocol#CreatingComments
+* https://developers.google.com/blogger/docs/2.0/developers_guide_protocol
+* https://support.google.com/blogger/answer/42064?hl=en
+* https://developers.google.com/blogger/docs/2.0/developers_guide_protocol#CreatingComments
+
+Test command line::
 
-test command line:
-curl localhost:8080/webmention/blogger \
-  -d 'source=http://localhost/response.html&target=http://freedom-io-2.blogspot.com/2014/04/blog-post.html'
+    curl localhost:8080/webmention/blogger -d 'source=http://localhost/response.html&target=http://freedom-io-2.blogspot.com/2014/04/blog-post.html'
 """
 import collections
 import logging
@@ -70,8 +69,9 @@ def new(auth_entity=None, blog_id=None, **kwargs):
     """Creates and returns a Blogger for the logged in user.
 
     Args:
-      auth_entity: :class:`oauth_dropins.blogger.BloggerV2Auth`
-      blog_id: which blog. optional. if not provided, uses the first available.
+      auth_entity (oauth_dropins.blogger.BloggerV2Auth):
+      blog_id (str): which blog, optional; if not provided, uses the first
+        available
     """
     urls, domains = Blogger.urls_and_domains(auth_entity, blog_id=blog_id)
     if not urls or not domains:
@@ -100,11 +100,11 @@ def urls_and_domains(auth_entity, blog_id=None):
     """Returns an auth entity's URL and domain.
 
     Args:
-      auth_entity: oauth_dropins.blogger.BloggerV2Auth
+      auth_entity (oauth_dropins.blogger.BloggerV2Auth):
       blog_id: which blog. optional. if not provided, uses the first available.
 
     Returns:
-      ([string url], [string domain])
+      ([str url], [str domain])
     """
     for id, host in zip(auth_entity.blog_ids, auth_entity.blog_hostnames):
       if blog_id == id or (not blog_id and host):
@@ -118,16 +118,16 @@ def create_comment(self, post_url, author_name, author_url, content, client=None
     Must be implemented by subclasses.
 
     Args:
-      post_url: string
-      author_name: string
-      author_url: string
-      content: string
-      client: :class:`gdata.blogger.client.BloggerClient`. If None, one will be
+      post_url (str)
+      author_name (str)
+      author_url (str)
+      content (str)
+      client (gdata.blogger.client.BloggerClient): If None, one will be
         created from auth_entity. Used for dependency injection in the unit
         test.
 
     Returns:
-      JSON response dict with 'id' and other fields
+      dict: JSON response with ``id`` and other fields
     """
     if client is None:
       client = self.auth_entity.get().api()

browser.py

@@ -1,5 +1,4 @@
-"""Browser extension views.
-"""
+"""Browser extension views."""
 import copy
 import logging
 from operator import itemgetter
@@ -31,10 +30,11 @@ def merge_by_id(existing, updates):
   with the same id. Requires all objects to have ids.
 
   Args:
-    existing: sequence of AS1 dicts
-    updates: sequence of AS1 dicts
+    existing (list of dict): AS1 objects
+    updates (list of dict): AS1 objects
 
-  Returns: merged list of AS1 dicts
+  Returns:
+    list of dict: merged objects
   """
   objs = {o['id']: o for o in existing}
   objs.update({o['id']: o for o in updates})
@@ -62,9 +62,10 @@ def key_id_from_actor(cls, actor):
     To be implemented by subclasses.
 
     Args:
-      actor: dict AS1 actor
+      actor (dict): AS1 actor
 
-    Returns: str, key id to use for the corresponding datastore entity
+    Returns:
+      str: key id to use for the corresponding datastore entity
     """
     raise NotImplementedError()
 
@@ -74,7 +75,7 @@ def new(cls, auth_entity=None, actor=None, **kwargs):
 
     Args:
       auth_entity: unused
-      actor: dict AS1 actor
+      actor (dict): AS1 actor
     """
     assert not auth_entity
     assert actor
@@ -151,10 +152,9 @@ def gr_source(self):
   def check_token(self, load_source=True):
     """Loads the token and checks that it has at least one domain registered.
 
-    Expects token in the `token` query param.
+    Expects token in the ``token`` query param.
 
-    Raises: :class:`HTTPException` with HTTP 403 if the token is missing or
-      invalid
+    Raises (HTTPException): HTTP 403 if the token is missing or invalid
     """
     token = request.values['token']
     domains = Domain.query(Domain.tokens == token).fetch()
@@ -165,7 +165,7 @@ def check_token(self, load_source=True):
   def auth(self):
     """Checks token and loads and returns the source.
 
-    Raises: :class:`HTTPException` with HTTP 400 or 403
+    Raises (HTTPException): HTTP 400 or 403
     """
     self.check_token()
     return util.load_source(error_fn=self.error)
@@ -181,8 +181,8 @@ class Status(BrowserView):
   """Runs preflight checks for a source and returns status and config info.
 
   Response body is a JSON map with these fields:
-    status: string, 'enabled' or 'disabled'
-    poll-seconds: integer, current poll frequency for this source in seconds
+    status (str): ``enabled`` or ``disabled``
+    poll-seconds (int): current poll frequency for this source in seconds
   """
   def dispatch_request(self):
     source = self.auth()
@@ -323,13 +323,13 @@ def update_activity():
 class Extras(BrowserView):
   """Merges extras (comments, reactions) from silo HTML into an existing Activity.
 
-  Requires the request parameter `id` with the silo post's id (not shortcode!).
+  Requires the request parameter ``id`` with the silo post's id (not shortcode!).
 
   Response body is the translated ActivityStreams JSON for the extras.
 
-  Subclasses must populate the MERGE_METHOD constant with the string name of the
-  granary source class's method that parses extras from silo HTML and merges
-  them into an activity.
+  Subclasses must populate the :attr:`MERGE_METHOD` constant with the string
+  name of the granary source class's method that parses extras from silo HTML
+  and merges them into an activity.
   """
   MERGE_METHOD = None
 

cron.py

@@ -29,7 +29,7 @@
 class LastUpdatedPicture(StringIdModel):
   """Stores the last user in a given silo that we updated profile picture for.
 
-  Key id is the silo's SHORT_NAME.
+  Key id is the silo's ``SHORT_NAME``.
   """
   last = ndb.KeyProperty()
   created = ndb.DateTimeProperty(auto_now_add=True, required=True, tzinfo=timezone.utc)

docs/conf.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # Sphinx build configuration file.
 #
 # This file is execfile()d with the current directory set to its
@@ -80,7 +78,7 @@
 
 # General information about the project.
 project = 'Bridgy'
-copyright = '2011-2022, Ryan Barrett'
+copyright = '2011-2023, Ryan Barrett'
 author = 'Ryan Barrett'
 
 # The version info for the project you're documenting, acts as replacement for

docs/index.rst

@@ -434,7 +434,9 @@ dataset <https://console.cloud.google.com/bigquery?p=brid-gy&d=datastore&page=da
    into BigQuery.* Also, expect this to cost around $10.
 
 2. Wait for it to be done with
-   ``gcloud datastore operations list | grep done``.
+   ``gcloud datastore operations list | grep done`` or by watching the
+   `Datastore Import/Export
+   page <https://console.cloud.google.com/datastore/databases/-default-/import-export?project=brid-gy>`__.
 
 3. `Import it into
    BigQuery <https://cloud.google.com/bigquery/docs/loading-data-cloud-datastore#loading_cloud_datastore_export_service_data>`__:
@@ -456,13 +458,14 @@ https://console.cloud.google.com/datastore/entities;kind=Response;ns=\ **:math:`
 Open the existing ``Response`` table in BigQuery:
 https://console.cloud.google.com/bigquery?project=brid-gy&ws=%211m10%211m4%214m3%211sbrid-gy%212sdatastore%213sResponse%211m4%211m3%211sbrid-gy%212sbquxjob_371f97c8_18131ff6e69%213sUS
 
-Query for the same first few rows sorted by ``updated`` ascending, check
-that they’re the same:
+Update the year in the queries below to two years before today. Query
+for the same first few rows sorted by ``updated`` ascending, check that
+they’re the same:
 
 ::
 
    SELECT * FROM `brid-gy.datastore.Response`
-   WHERE updated >= TIMESTAMP('2020-11-01T00:00:00Z')
+   WHERE updated >= TIMESTAMP('202X-11-01T00:00:00Z')
    ORDER BY updated ASC
    LIMIT 10
 
@@ -471,7 +474,7 @@ Delete those rows:
 ::
 
    DELETE FROM `brid-gy.datastore.Response`
-   WHERE updated >= TIMESTAMP('2020-11-01T00:00:00Z')
+   WHERE updated >= TIMESTAMP('202X-11-01T00:00:00Z')
 
 Load the new ``Response`` entities into a temporary table:
 
@@ -538,7 +541,7 @@ nullable.
    Import the CSV, replacing the *data* sheet.
 4. Change the underscores in column headings to spaces.
 5. Open each sheet, edit the chart, and extend the data range to include
-   all of thee new rows.
+   all of the new rows.
 6. Check out the graphs! Save full size images with OS or browser
    screenshots, thumbnails with the *Download Chart* button. Then post
    them!
@@ -557,7 +560,8 @@ for long term storage.
 
 I use the `Datastore Bulk Delete Dataflow
 template <https://cloud.google.com/dataflow/docs/guides/templates/provided-utilities#datastore-bulk-delete>`__
-with a GQL query like this:
+with a GQL query like this. (Update the years below to two years before
+today.)
 
 .. code:: sql
 
@@ -573,7 +577,7 @@ command line:
      --gcs-location gs://dataflow-templates-us-central1/latest/Datastore_to_Datastore_Delete
      --region us-central1
      --staging-location gs://brid-gy.appspot.com/tmp-datastore-delete
-     --parameters datastoreReadGqlQuery="SELECT * FROM `Response` WHERE updated < DATETIME('2020-11-01T00:00:00Z'),datastoreReadProjectId=brid-gy,datastoreDeleteProjectId=brid-gy"
+     --parameters datastoreReadGqlQuery="SELECT * FROM `Response` WHERE updated < DATETIME('202X-11-01T00:00:00Z'),datastoreReadProjectId=brid-gy,datastoreDeleteProjectId=brid-gy"
 
 Expect this to take at least a day or so.