lots more doc formatting updates

docs/conf.py

@@ -336,10 +336,12 @@
 intersphinx_mapping = {
   'flask': ('https://flask.palletsprojects.com/en/latest', None),
   'flask_caching': ('https://flask-caching.readthedocs.io/en/latest', None),
-  'oauth_dropins': ('https://oauth-dropins.readthedocs.io/en/latest', None),
+  'oauth_dropins': ('https://oauth-dropins.readthedocs.io/en/stable', None),
+  'praw': ('https://praw.readthedocs.io/en/stable', None),
   'python': ('https://docs.python.org/3/', None),
-  'requests': ('https://requests.readthedocs.io/en/stable/', None),
-  'urllib3': ('https://urllib3.readthedocs.io/en/latest', None),
-  'webob': ('https://webob.readthedocs.io/en/latest', None),
-  'werkzeug': ('https://werkzeug.palletsprojects.com/en/latest/', None),
+  'requests': ('https://requests.readthedocs.io/en/stable', None),
+  'urllib3': ('https://urllib3.readthedocs.io/en/stable', None),
+  'webob': ('https://webob.readthedocs.io/en/stable', None),
+  'websockets': ('https://websockets.readthedocs.io/en/stable', None),
+  'werkzeug': ('https://werkzeug.palletsprojects.com/en/latest', None),
 }

docs/source/granary.rst

@@ -8,72 +8,89 @@ Reference documentation.
 as1
 ---
 .. automodule:: granary.as1
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 as2
 ---
 .. automodule:: granary.as2
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 atom
 ----
 .. automodule:: granary.atom
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 bluesky
 -------
 .. automodule:: granary.bluesky
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 facebook
 --------
 .. automodule:: granary.facebook
-    :exclude-members: __getnewargs__, __getstate__, __new__, __repr__
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 flickr
 ------
 .. automodule:: granary.flickr
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 github
 ------
 .. automodule:: granary.github
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 instagram
 ---------
 .. automodule:: granary.instagram
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 jsonfeed
 --------
 .. automodule:: granary.jsonfeed
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 mastodon
 --------
 .. automodule:: granary.mastodon
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 meetup
 ------
 .. automodule:: granary.meetup
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 microformats2
 -------------
 .. automodule:: granary.microformats2
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 nostr
 -----
 .. automodule:: granary.nostr
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 pixelfed
 --------
 .. automodule:: granary.pixelfed
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 reddit
 ------
 .. automodule:: granary.reddit
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 rss
 ---
 .. automodule:: granary.rss
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 source
 ------
 .. automodule:: granary.source
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 twitter
 -------
 .. automodule:: granary.twitter
+    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__

granary/as1.py

@@ -76,7 +76,7 @@ def get_object(obj, field='object'):
     field (str)
 
   Returns:
-    dict
+    dict:
   """
   if not obj:
     return {}
@@ -95,7 +95,7 @@ def get_objects(obj, field='object'):
     field (str)
 
   Returns:
-    sequence of dict
+    sequence of dict:
   """
   if not obj:
     return []
@@ -117,7 +117,7 @@ def get_owner(obj):
     obj (dict): decoded JSON ActivityStreams object
 
   Returns:
-    str
+    str:
   """
   if not obj:
     return None
@@ -188,11 +188,11 @@ def is_public(obj):
   http://activitystrea.ms/specs/json/targeting/1.0/
 
   Expects values generated by this library: ``objectType`` ``group``, ``alias``
-  @public``, ``@unlisted``, or ``@private``.
+  ``@public``, ``@unlisted``, or ``@private``.
 
   Also, important point: this defaults to True, ie public. Bridgy depends on
   that and prunes the to field from stored activities in Response objects (in
-  ``bridgy/util.prune_activity()``). If the default here ever changes, be sure to
+  ``bridgy/util.prune_activity``). If the default here ever changes, be sure to
   update Bridgy's code.
   """
   to = obj.get('to') or get_object(obj).get('to') or []
@@ -209,7 +209,7 @@ def add_rsvps_to_event(event, rsvps):
 
   Args:
     event (dict): ActivityStreams event object
-    rsvps (sequence dict): ActivityStreams RSVP activity objects
+    rsvps (sequence of dict): ActivityStreams RSVP activity objects
   """
   for rsvp in rsvps:
     field = RSVP_VERB_TO_COLLECTION.get(rsvp.get('verb'))
@@ -264,15 +264,15 @@ def activity_changed(before, after, log=False):
   """Returns whether two activities or objects differ meaningfully.
 
   Only compares a few fields: ``objectType``, ``verb``, ``content``,
-  ``location``, and ``image`. Notably does *not* compare ``author``,
+  ``location``, and ``image``. Notably does *not* compare ``author``,
   ``published``, or ``updated``.
 
   Args:
     before: dict, ActivityStreams activity or object
     after: dict, ActivityStreams activity or object
 
   Returns:
-    bool
+    bool:
   """
   def changed(b, a, field, label, ignore=None):
     b_val = b.get(field)
@@ -306,11 +306,11 @@ def changed(b, a, field, label, ignore=None):
 
 
 def append_in_reply_to(before, after):
-  """Appends before's ``inReplyTo``s to after, in place.
+  """Appends before's ``inReplyTo`` to ``after``, in place.
 
   Args:
-    before: dict, ActivityStreams activity or object
-    after: dict, ActivityStreams activity or object
+    before (dict): ActivityStreams activity or object
+    after (dict): ActivityStreams activity or object
   """
   obj_b = get_object(before) or before
   obj_a = get_object(after) or after
@@ -358,7 +358,7 @@ def original_post_discovery(
     kwargs: passed to :func:`requests.head` when following redirects
 
   Returns:
-    (list of str, list of str): original post URLs, mentions tuple
+    (list of str, list of str) tuple: (original post URLs, mentions)
   """
   obj = get_object(activity) or activity
   content = obj.get('content', '').strip()

granary/atom.py

@@ -52,7 +52,7 @@ def _text(elem, field=None):
     field (str)
 
   Returns:
-    str or None
+    str or None:
   """
   if field:
     if ':' not in field:
@@ -78,7 +78,7 @@ def _as1_value(elem, field):
     field (str)
 
   Returns:
-    str or None
+    str or None:
   """
   type = _text(elem, f'activity:{field}')
   if type:

granary/bluesky.py

@@ -71,7 +71,7 @@ def url_to_did_web(url):
     url (str)
 
   Returns:
-    str
+    str:
   """
   parsed = urllib.parse.urlparse(url)
   if not parsed.hostname:
@@ -102,7 +102,7 @@ def did_web_to_url(did):
     did (str)
 
   Returns:
-    str
+    str:
   """
   if not did or not DID_WEB_PATTERN.match(did):
     raise ValueError(f'Invalid did:web: {did}')

granary/facebook.py

@@ -533,7 +533,7 @@ def get_share(self, activity_user_id, activity_id, share_id, activity=None):
       activity (dict): activity object, optional
 
     Returns:
-      dict
+      dict:
     """
     orig_id = f'{activity_user_id}_{activity_id}'
 
@@ -581,7 +581,7 @@ def get_reaction(self, activity_user_id, activity_id, reaction_user_id,
       activity (dict): activity object (optional)
 
     Returns:
-      dict
+      dict:
     """
     if '_' not in reaction_id:  # handle just name of reaction type
       reaction_id = f'{activity_id}_{reaction_id}_by_{reaction_user_id}'
@@ -920,7 +920,7 @@ def base_id(cls, url):
     """Guesses the id of the object in the given URL.
 
     Returns:
-      str or None
+      str or None:
     """
     params = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)
     event_id = params.get('event_time_id')
@@ -2195,7 +2195,7 @@ def _scraped_content(cls, tag):
       tag (bs4.Tag)
 
     Returns:
-      str
+      str:
     """
     # TODO: distinguish between text elements with actual whitespace
     # before/after and without. this adds space to all of them, including
@@ -2602,7 +2602,7 @@ def urlopen_batch_full(self, requests):
           ]
 
     Returns:
-      (sequence of dict): responses in Facebook's batch format, except that body
+      sequence of dict: responses in Facebook's batch format, except that body
       is JSON-decoded if possible, and headers is a single dict, not a list of
       dicts, e.g.::
 

granary/flickr.py

@@ -366,7 +366,7 @@ def preview_delete(self, id):
       id (int or str): photo id to delete
 
     Returns:
-      ``CreationResult``
+      CreationResult:
     """
     return source.creation_result(
       description=f'<span class="verb">delete</span> <a href="{self.photo_url(self.user_id(), id)}">this photo</a>.')
@@ -732,7 +732,7 @@ def user_id(self):
     https://www.flickr.com/services/api/flickr.people.getLimits.html
 
     Returns:
-      str
+      str:
     """
     if not self._user_id:
       resp = self.call_api_method('flickr.people.getLimits')
@@ -748,7 +748,7 @@ def path_alias(self):
     https://www.flickr.com/services/api/flickr.people.getInfo.html
 
     Returns:
-      str
+      str:
     """
     if not self._path_alias:
       resp = self.call_api_method('flickr.people.getInfo', {
@@ -764,7 +764,7 @@ def user_url(self, user_id):
       user_id (str): user's alphanumeric ``nsid`` or path alias
 
     Returns:
-      str, a profile URL
+      str: a profile URL
     """
     return user_id and f'https://www.flickr.com/people/{user_id}/'
 

granary/github.py

@@ -266,7 +266,7 @@ def base_id(cls, url):
       url (str):
 
     Returns:
-      str or None
+      str or None:
     """
     parts = urllib.parse.urlparse(url).path.strip('/').split('/')
     if len(parts) == 4 and util.is_int(parts[3]):
@@ -752,7 +752,7 @@ def existing_labels(self, owner, repo):
       repo (str)
 
     Returns:
-      set of str
+      set of str:
     """
     resp = self.graphql(GRAPHQL_REPO_LABELS, locals())
 

granary/microformats2.py

@@ -1212,7 +1212,7 @@ def tags_to_html(tags, classname, visible=True):
     visible (bool): whether to visibly include ``displayName``
 
   Returns:
-    str
+    str:
   """
   urls = {}  # stores (url, displayName) tuples
   for tag in tags:
@@ -1275,7 +1275,7 @@ def img(src, alt=''):
     alt (str): ``alt`` attribute value, or None
 
   Returns:
-    str
+    str:
   """
   if isinstance(src, dict):
     assert not alt
@@ -1292,7 +1292,7 @@ def vid(src, poster=''):
     poster (str): optional URL of the poster or preview image
 
   Returns:
-    str
+    str:
   """
   poster_img = f'<img src="{poster}" />' if poster else ''
 
@@ -1308,7 +1308,7 @@ def aud(src):
     src (str): URL of the audio
 
   Returns:
-    str
+    str:
   """
   return f'<audio class="u-audio" src="{src}" controls="controls">Your browser does not support the audio tag. <a href="{src}">Click here to listen directly.</a></audio>'
 
@@ -1323,7 +1323,7 @@ def maybe_linked(text, url=None, linked_classname=None, unlinked_classname=None)
     unlinked_classname (str): optional ``class`` attribute to use if not ``url``
 
   Returns:
-    str
+    str:
   """
   if url:
     classname = f' class="{linked_classname}"' if linked_classname else ''
@@ -1341,7 +1341,7 @@ def maybe_datetime(dt, classname):
     classname (str): class name
 
   Returns:
-    str
+    str:
   """
   if dt:
     return f'<time class="{classname}" datetime="{dt}">{dt}</time>'