docs: sphinx config updates

Author: snarfed

docs/_static/custom.css

@@ -7,6 +7,12 @@
   color:#fcfcfc;
 }
 
+.rst-content code.literal,
+.rst-content tt.literal {
+  /* overrides theme */
+  color: darkgreen;
+}
+
 .rst-content code, .rst-content tt, code {
   border: none;
   padding: 0;

docs/conf.py

@@ -46,8 +46,13 @@
 autodoc_default_options = {
     'show-inheritance': True,
     'members': True,
-    'special-members': True,
+    'private-members': '_convert, _handle',
+    'no-undoc-members': True,
+    'no-special-members': True,
+    'no-imported-members': True,
+    'member-order': 'bysource',
 }
+autodoc_inherit_docstrings = False
 
 # Napoleon settings
 # http://www.sphinx-doc.org/en/stable/ext/napoleon.html
@@ -78,7 +83,7 @@
 
 # General information about the project.
 project = 'Bridgy'
-copyright = '2011-2023, Ryan Barrett'
+copyright = '2011-2025, Ryan Barrett'
 author = 'Ryan Barrett'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -117,7 +122,8 @@
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#add_module_names = True
+add_module_names = False
+python_use_unqualified_type_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
@@ -337,6 +343,7 @@
   'flask': ('https://flask.palletsprojects.com/en/latest', None),
   'flask_caching': ('https://flask-caching.readthedocs.io/en/latest', None),
   'granary': ('https://granary.readthedocs.io/en/latest', None),
+  'lexrpc': ('https://lexrpc.readthedocs.io/en/stable', None),
   'ndb': ('https://googleapis.dev/python/python-ndb/latest/', None),
   'oauth_dropins': ('https://oauth-dropins.readthedocs.io/en/latest', None),
   'python': ('https://docs.python.org/3/', None),

docs/index.rst

@@ -27,11 +27,11 @@ Pull requests are welcome! Feel free to `ping me in
 
 First, fork and clone this repo. Then, install the `Google Cloud
 SDK <https://cloud.google.com/sdk/>`__ and run
-``gcloud components install beta cloud-datastore-emulator`` to install
-the `datastore
-emulator <https://cloud.google.com/datastore/docs/tools/datastore-emulator>`__.
-Once you have them, set up your environment by running these commands in
-the repo root directory:
+``gcloud components install cloud-firestore-emulator`` to install the
+`Firestore
+emulator <https://cloud.google.com/firestore/docs/emulator>`__. Once you
+have them, set up your environment by running these commands in the repo
+root directory:
 
 .. code:: sh
 
@@ -46,7 +46,7 @@ Now, you can fire up the gcloud emulator and run the tests:
 
 .. code:: sh
 
-   gcloud beta emulators datastore start --use-firestore-in-datastore-mode --no-store-on-disk --host-port=localhost:8089 --quiet < /dev/null >& /dev/null &
+   gcloud emulators firestore start --host-port=:8089 --database-mode=datastore-mode < /dev/null >& /dev/null &
    python3 -m unittest discover -s tests -t .
    kill %1
 
@@ -58,7 +58,7 @@ To run the app locally, use
 
 .. code:: shell
 
-   gcloud beta emulators datastore start --use-firestore-in-datastore-mode --no-store-on-disk --host-port=localhost:8089 --quiet < /dev/null >& /dev/null &
+   gcloud emulators firestore start --host-port=:8089 --database-mode=datastore-mode < /dev/null >& /dev/null &
    GAE_ENV=localdev FLASK_ENV=development flask run -p 8080
 
 Open `localhost:8080 <http://localhost:8080/>`__ and you should see the
@@ -85,7 +85,7 @@ background task processing service, eg:
 
 .. code:: shell
 
-   gcloud beta emulators datastore start --consistency=1.0 --host-port=localhost:8089 --quiet
+   gcloud emulators firestore start --host-port=:8089 --database-mode=datastore-mode
    GAE_ENV=localdev FLASK_ENV=development flask run -p 8080
 
 Now, run the ``curl`` command you constructed above.
@@ -238,74 +238,74 @@ Browser extension: Changelog
 
 0.7.0, 2024-01-03
 
--  Remove Instgram. Their anti-bot defenses have led them to suspend a
-   couple people’s accounts for using this extension, so we’re disabling
-   it out of an abundance of caution. Sorry for the bad news.
+- Remove Instgram. Their anti-bot defenses have led them to suspend a
+  couple people’s accounts for using this extension, so we’re disabling
+  it out of an abundance of caution. Sorry for the bad news.
 
 0.6.1, 2022-09-18
 
--  Don’t open silo login pages if they’re not logged in. This ran at
-   extension startup time, which was mostly harmless in manifest v2
-   since the background page was persistent stayed loaded, but in
-   manifest v3 it’s a service worker or non-persistent background page,
-   which gets unloaded and then reloaded every 5m.
+- Don’t open silo login pages if they’re not logged in. This ran at
+  extension startup time, which was mostly harmless in manifest v2 since
+  the background page was persistent stayed loaded, but in manifest v3
+  it’s a service worker or non-persistent background page, which gets
+  unloaded and then reloaded every 5m.
 
 0.6.0, 2022-09-17
 
--  Migrate Chrome (`but not
-   Firefox <https://blog.mozilla.org/addons/2022/05/18/manifest-v3-in-firefox-recap-next-steps/>`__)
-   `from Manifest v2 to
-   v3 <https://developer.chrome.com/docs/extensions/mv3/intro/mv3-migration/#man-sw>`__.
+- Migrate Chrome (`but not
+  Firefox <https://blog.mozilla.org/addons/2022/05/18/manifest-v3-in-firefox-recap-next-steps/>`__)
+  `from Manifest v2 to
+  v3 <https://developer.chrome.com/docs/extensions/mv3/intro/mv3-migration/#man-sw>`__.
 
 0.5, 2022-07-21
 
--  Update Instagram scraping.
+- Update Instagram scraping.
 
 0.4, 2022-01-30
 
--  Fix Instagram comments. Add extra client side API fetch, forward to
-   new Bridgy endpoint.
--  Expand error messages in options UI.
+- Fix Instagram comments. Add extra client side API fetch, forward to
+  new Bridgy endpoint.
+- Expand error messages in options UI.
 
 0.3.5, 2021-03-04
 
--  Dynamically adjust polling frequency per silo based on how often
-   we’re seeing new comments and reactions, how recent the last
-   successful webmention was, etc.
+- Dynamically adjust polling frequency per silo based on how often we’re
+  seeing new comments and reactions, how recent the last successful
+  webmention was, etc.
 
 0.3.4, 2021-02-22
 
--  Allow individually enabling or disabling Instagram and Facebook.
+- Allow individually enabling or disabling Instagram and Facebook.
 
 0.3.3, 2021-02-20
 
--  Only override requests from the browser extension, not all requests
-   to the silos’ domains.
+- Only override requests from the browser extension, not all requests to
+  the silos’ domains.
 
 0.3.2, 2021-02-18
 
--  Fix compatibility with Facebook Container Tabs.
+- Fix compatibility with Facebook Container Tabs.
 
 0.3.1, 2021-02-17
 
--  Add Facebook support!
+- Add Facebook support!
 
 0.2.1, 2021-01-09
 
--  Add more details to extensions option page: Instagram login, Bridgy
-   IndieAuth registration, etc.
--  Support Firefox’s Facebook Container Tabs addon.
+- Add more details to extensions option page: Instagram login, Bridgy
+  IndieAuth registration, etc.
+- Support Firefox’s Facebook Container Tabs addon.
 
 0.2, 2021-01-03
 
--  Add IndieAuth login on https://brid.gy/ and token handling.
--  Add extension settings page with status info and buttons to login
-   again and poll now.
--  Better error handling.
+- Add IndieAuth login on https://brid.gy/ and token handling.
+- Add extension settings page with status info and buttons to login
+  again and poll now.
+- Better error handling.
 
 0.1.5, 2020-12-25
 
--  Initial beta release!
+- Initial beta release!
 
 Adding a new silo
 -----------------
@@ -466,9 +466,9 @@ 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
 
-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:
+Update the year in the queries below to three years before this year.
+Query for the same first few rows sorted by ``updated`` ascending, check
+that they’re the same:
 
 ::
 

docs/requirements.txt

@@ -1,2 +1,2 @@
-sphinx>=5.3.0
-sphinx-rtd-theme>=1.1.1
+sphinx>=8.1.3
+sphinx-rtd-theme>=3.0.2

docs/source/modules.rst

@@ -8,124 +8,99 @@ Reference documentation.
 admin
 -----
 .. automodule:: admin
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 blog_webmention
 ---------------
 .. automodule:: blog_webmention
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 blogger
 -------
 .. automodule:: blogger
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 browser
 -------
 .. automodule:: browser
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 cron
 ----
 .. automodule:: cron
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 facebook
 --------
 .. automodule:: facebook
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 flickr
 ------
 .. automodule:: flickr
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 github
 ------
 .. automodule:: github
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 handlers
 --------
 .. automodule:: handlers
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 indieauth
 ---------
 .. automodule:: indieauth
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 instagram
 ---------
 .. automodule:: instagram
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 mastodon
 --------
 .. automodule:: mastodon
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 medium
 ------
 .. automodule:: medium
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 models
 ------
 .. automodule:: models
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 original_post_discovery
 -----------------------
 .. automodule:: original_post_discovery
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 pages
 -----
 .. automodule:: pages
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 publish
 -------
 .. automodule:: publish
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 reddit
 ------
 .. automodule:: reddit
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 superfeedr
 ----------
 .. automodule:: superfeedr
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 tasks
 -----
 .. automodule:: tasks
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 tumblr
 ------
 .. automodule:: tumblr
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 twitter
 -------
 .. automodule:: twitter
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 util
 ----
 .. automodule:: util
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 webmention
 ----------
 .. automodule:: webmention
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__
 
 wordpress_rest
 --------------
 .. automodule:: wordpress_rest
-    :exclude-members: __eq__, __getnewargs__, __getstate__, __hash__, __new__, __repr__, __str__, __weakref__

util.py

@@ -424,7 +424,7 @@ def prune_response(response):
 
 
 def replace_test_domains_with_localhost(url):
-  """Replace domains in ``LOCALHOST_TEST_DOMAINS` with localhost for testing.
+  """Replace domains in ``LOCALHOST_TEST_DOMAINS`` with localhost for testing.
 
   Args:
     url (str)
@@ -486,7 +486,7 @@ def maybe_add_or_delete_source(source_cls, auth_entity, state, **kwargs):
 
   This method _always_ ends by raising a :class:`Redirect` exception to return
   an HTTP redirect response! That means that any code after a call to this
-  function _will not run_!
+  function *will not run!*
 
   Args:
     source_cls (granary.source.Source subclass): eg