From 89f0cb10b76881e8f88f4e3debab953583d2352c Mon Sep 17 00:00:00 2001 From: Ryan Barrett Date: Fri, 31 Jan 2025 10:25:23 -0800 Subject: [PATCH] docs: sphinx config updates --- docs/_static/custom.css | 6 ++++ docs/conf.py | 11 ++++-- docs/index.rst | 75 ++++++++++++++++++++++++----------------- docs/requirements.txt | 4 +-- docs/source/granary.rst | 18 ---------- granary/atom.py | 2 +- granary/bluesky.py | 2 +- granary/facebook.py | 18 +++++----- 8 files changed, 72 insertions(+), 64 deletions(-) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 79601933..8d0301af 100644 --- a/docs/_static/custom.css +++ b/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; diff --git a/docs/conf.py b/docs/conf.py index be7a0c13..99e98aab 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,13 +43,19 @@ ] # autodoc settings +# http://www.sphinx-doc.org/en/stable/ext/autodoc.html autoclass_content = 'class' autodoc_member_order = 'bysource' 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 @@ -118,7 +124,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. diff --git a/docs/index.rst b/docs/index.rst index 437f44a0..428413b6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -449,7 +449,18 @@ Facebook and Twitter’s raw HTML. Changelog --------- -8.0 - unreleased +8.1 - unreleased +~~~~~~~~~~~~~~~~ + +- ``as2``: + + - ``to_as1``: support integer seconds ``duration``, which is + non-standard but sent by some AP implementations, `eg + Funkwhale `__. + - ``link_tags``: add ``class="hashtag"`` for hashtag (``Tag``) tags + (`bridgy-fed/#1634 `__). + +8.0 - 2025-01-01 ~~~~~~~~~~~~~~~~ *Breaking changes:* @@ -584,6 +595,8 @@ removed until at least v9.0, if not later. boolean kwarg to fetch and generate a preview ``attachment`` for the first link in the HTML ``content``, if any. +.. _section-1: + 7.0 - 2024-06-24 ~~~~~~~~~~~~~~~~ @@ -703,7 +716,7 @@ removed until at least v9.0, if not later. - ``Source.postprocess``: when extracting @-mentions, defer to existing tag if it has the same ``displayName`` and has ``url``. -.. _section-1: +.. _section-2: 6.2 - 2024-03-15 ~~~~~~~~~~~~~~~~ @@ -861,7 +874,7 @@ removed until at least v9.0, if not later. - ``postprocess_activity/object``: add ``mentions`` kwarg to convert @-mentions in HTML links to ``mention`` tags. -.. _section-2: +.. _section-3: 6.1 - 2023-09-16 ~~~~~~~~~~~~~~~~ @@ -999,7 +1012,7 @@ at least in the REST API. - ``from_activities``: handle bare string id ``author``. -.. _section-3: +.. _section-4: 6.0 - 2023-03-22 ~~~~~~~~~~~~~~~~ @@ -1111,7 +1124,7 @@ at least in the REST API. - ``from_activities``: fix item ordering to match input activities. -.. _section-4: +.. _section-5: 5.0 - 2022-12-03 ~~~~~~~~~~~~~~~~ @@ -1245,7 +1258,7 @@ at least in the REST API. - ``Source.original_post_discovery``: add new ``max_redirect_fetches`` keyword arg. -.. _section-5: +.. _section-6: 4.0 - 2022-03-23 ~~~~~~~~~~~~~~~~ @@ -1291,7 +1304,7 @@ at least in the REST API. - Handle malformed ``items.author`` element. -.. _section-6: +.. _section-7: 3.2 - 2021-09-15 ~~~~~~~~~~~~~~~~ @@ -1348,7 +1361,7 @@ at least in the REST API. - REST API: ported web framework from webapp2 to Flask. No user-visible behavior change expected. -.. _section-7: +.. _section-8: 3.1 - 2021-04-03 ~~~~~~~~~~~~~~~~ @@ -1453,7 +1466,7 @@ at least in the REST API. - ``from_as1()``: convert ``username`` to ``preferredUsername``. - ``from_as1()``: bug fix, make ``context`` kwarg actually work. -.. _section-8: +.. _section-9: 3.0 - 2020-04-08 ~~~~~~~~~~~~~~~~ @@ -1531,7 +1544,7 @@ Non-breaking changes: caching now. - Added Meetup.com support for publishing RSVPs. -.. _section-9: +.. _section-10: 2.2 - 2019-11-02 ~~~~~~~~~~~~~~~~ @@ -1580,7 +1593,7 @@ Non-breaking changes: enclosure per item, so we now only include the first, and log a warning if the activity has more.) -.. _section-10: +.. _section-11: 2.1 - 2019-09-04 ~~~~~~~~~~~~~~~~ @@ -1630,7 +1643,7 @@ Non-breaking changes: - Default title to ellipsized content. -.. _section-11: +.. _section-12: 2.0 - 2019-03-01 ~~~~~~~~~~~~~~~~ @@ -1639,7 +1652,7 @@ Non-breaking changes: March `__. Notably, this removes the ``googleplus`` module. -.. _section-12: +.. _section-13: 1.15 - 2019-02-28 ~~~~~~~~~~~~~~~~~ @@ -1690,7 +1703,7 @@ removes the ``googleplus`` module. - ``/url``: Return HTTP 400 when fetching the user’s URL results in an infinite redirect. -.. _section-13: +.. _section-14: 1.14 - 2018-11-12 ~~~~~~~~~~~~~~~~~ @@ -1717,7 +1730,7 @@ Encode ``&``\ s in author URL and email address too. (Thanks `sebsued `__!) \* AS2: \* Add ``Follow`` support. -.. _section-14: +.. _section-15: 1.13 - 2018-08-08 ~~~~~~~~~~~~~~~~~ @@ -1777,7 +1790,7 @@ support. - Support ``alt`` attribute in ```` tags (`snarfed/bridgy#756 `__). -.. _section-15: +.. _section-16: 1.12 - 2018-03-24 ~~~~~~~~~~~~~~~~~ @@ -1812,7 +1825,7 @@ impact of the Python 3 migration. It *should* be a noop for existing Python 2 users, and we’ve tested thoroughly, but I’m sure there are still bugs. Please file issues if you notice anything broken! -.. _section-16: +.. _section-17: 1.11 - 2018-03-09 ~~~~~~~~~~~~~~~~~ @@ -1884,7 +1897,7 @@ still bugs. Please file issues if you notice anything broken! - Omit title from items if it’s the same as the content. (Often caused by microformats2’s implied ``p-name`` logic.) -.. _section-17: +.. _section-18: 1.10 - 2017-12-10 ~~~~~~~~~~~~~~~~~ @@ -1925,7 +1938,7 @@ still bugs. Please file issues if you notice anything broken! - Fix bug that omitted title in some cases (`#122 `__). -.. _section-18: +.. _section-19: 1.9 - 2017-10-24 ~~~~~~~~~~~~~~~~ @@ -1952,7 +1965,7 @@ still bugs. Please file issues if you notice anything broken! ``json``, ``json-mf2``, and ``xml`` are still accepted, but deprecated. -.. _section-19: +.. _section-20: 1.8 - 2017-08-29 ~~~~~~~~~~~~~~~~ @@ -2029,7 +2042,7 @@ still bugs. Please file issues if you notice anything broken! `bug `__ `fixes `__. -.. _section-20: +.. _section-21: 1.7 - 2017-02-27 ~~~~~~~~~~~~~~~~ @@ -2076,7 +2089,7 @@ still bugs. Please file issues if you notice anything broken! “narrow” builds of Python 2 with ``--enable-unicode=ucs2``, which is the default on Mac OS X, Windows, and older \*nix. -.. _section-21: +.. _section-22: 1.6 - 2016-11-26 ~~~~~~~~~~~~~~~~ @@ -2110,7 +2123,7 @@ still bugs. Please file issues if you notice anything broken! - Error handling: return HTTP 502 for non-JSON API responses, 504 for connection failures. -.. _section-22: +.. _section-23: 1.5 - 2016-08-25 ~~~~~~~~~~~~~~~~ @@ -2147,14 +2160,14 @@ still bugs. Please file issues if you notice anything broken! - Switch creating comments and reactions from GraphQL to REST API (`bridgy#824 `__. -.. _section-23: +.. _section-24: 1.4.1 - 2016-06-27 ~~~~~~~~~~~~~~~~~~ - Bump oauth-dropins requirement to 1.4. -.. _section-24: +.. _section-25: 1.4.0 - 2016-06-27 ~~~~~~~~~~~~~~~~~~ @@ -2188,7 +2201,7 @@ still bugs. Please file issues if you notice anything broken! - Upgrade to requests 2.10.0 and requests-toolbelt 0.60, which support App Engine. -.. _section-25: +.. _section-26: 1.3.1 - 2016-04-07 ~~~~~~~~~~~~~~~~~~ @@ -2196,7 +2209,7 @@ still bugs. Please file issues if you notice anything broken! - Update `oauth-dropins `__ dependency to >=1.3. -.. _section-26: +.. _section-27: 1.3.0 - 2016-04-06 ~~~~~~~~~~~~~~~~~~ @@ -2239,7 +2252,7 @@ still bugs. Please file issues if you notice anything broken! - Misc bug fixes. - Set up Coveralls. -.. _section-27: +.. _section-28: 1.2.0 - 2016-01-11 ~~~~~~~~~~~~~~~~~~ @@ -2295,7 +2308,7 @@ still bugs. Please file issues if you notice anything broken! - Misc bug fixes. - Set up CircleCI. -.. _section-28: +.. _section-29: 1.1.0 - 2015-09-06 ~~~~~~~~~~~~~~~~~~ @@ -2318,7 +2331,7 @@ still bugs. Please file issues if you notice anything broken! - Improve original post discovery algorithm. - New logo. -.. _section-29: +.. _section-30: 1.0.1 - 2015-07-11 ~~~~~~~~~~~~~~~~~~ @@ -2326,7 +2339,7 @@ still bugs. Please file issues if you notice anything broken! - Bug fix for atom template rendering. - Facebook, Instagram: support access_token parameter. -.. _section-30: +.. _section-31: 1.0 - 2015-07-10 ~~~~~~~~~~~~~~~~ diff --git a/docs/requirements.txt b/docs/requirements.txt index 85fb07fc..b6aa00f4 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/granary.rst b/docs/source/granary.rst index 47cd927a..c43d67f3 100644 --- a/docs/source/granary.rst +++ b/docs/source/granary.rst @@ -8,89 +8,71 @@ 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: __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__ diff --git a/granary/atom.py b/granary/atom.py index e8ed33bd..780eed7e 100644 --- a/granary/atom.py +++ b/granary/atom.py @@ -126,7 +126,7 @@ def from_as1(input, actor=None, title=None, request_url=None, host_url=None, feed ```` element. xml_base (str): base URL, if any. Used in the top-level ``xml:base`` attribute. - rels (dict): rel links to include. Keys are string ``rel``s, values are + rels (dict): rel links to include. Keys are string ``rel``, values are string URLs. reader (bool): whether the output will be rendered in a feed reader. Currently just includes location if True, not otherwise. diff --git a/granary/bluesky.py b/granary/bluesky.py index 88c7fc31..ad8ac8db 100644 --- a/granary/bluesky.py +++ b/granary/bluesky.py @@ -1096,7 +1096,7 @@ def to_external_embed(obj, description=None, blobs=None): Args: obj (dict): AS1 object - description (str): if provided, overrides ``summary`` and ``content` in ``obj` + description (str): if provided, overrides ``summary`` and ``content`` in ``obj`` Returns: dict: Bluesky ``app.bsky.embed.external#external`` record diff --git a/granary/facebook.py b/granary/facebook.py index 3cd923d7..ac79cd44 100644 --- a/granary/facebook.py +++ b/granary/facebook.py @@ -1483,7 +1483,7 @@ def rsvp_to_as1(self, rsvp, type=None, event=None): Args: rsvp (dict): Facebook RSVP object type (str): optional Facebook RSVP type, one of ``RSVP_FIELDS`` - event (dict): Facebook event object. May contain only a single ``id` + event (dict): Facebook event object. May contain only a single ``id`` element. Returns: @@ -2424,21 +2424,21 @@ def parse_id(id, is_comment=False): Facebook ids come in different formats: * Simple number, usually a user or post: ``12`` - * Two numbers with underscore, usually ``POST_COMMENT`` or ``USER_POST``\: + * Two numbers with underscore, usually ``POST_COMMENT`` or ``USER_POST``: ``12_34`` - * Three numbers with underscores, ``USER_POST_COMMENT``\: ``12_34_56`` - * Three numbers with colons, ``USER:POST:SHARD``\: ``12:34:63`` + * Three numbers with underscores, ``USER_POST_COMMENT``: ``12_34_56`` + * Three numbers with colons, ``USER:POST:SHARD``: ``12:34:63`` (We're guessing that the third part is a shard in some FB internal system. In our experience so far, it's always either 63 or the app-scoped user id for 63.) - * Two numbers with colon, ``POST:SHARD``\: ``12:34`` + * Two numbers with colon, ``POST:SHARD``: ``12:34`` (We've seen 0 as shard in this format.) - * Four numbers with colons/underscore, ``USER:POST:SHARD_COMMENT``\: + * Four numbers with colons/underscore, ``USER:POST:SHARD_COMMENT``: ``12:34:63_56`` - * Five numbers with colons/underscore, ``USER:EVENT:UNKNOWN:UNKNOWN_UNKNOWN``\. + * Five numbers with colons/underscore, ``USER:EVENT:UNKNOWN:UNKNOWN_UNKNOWN``. Not currently supported! Examples: - * ``111599105530674:998145346924699:10102446236688861:10207188792305341_998153510257216`` - * ``111599105530674:195181727490727:10102446236688861:10205257726909910_195198790822354`` + * ``111599105530674:998145346924699:10102446236688861:10207188792305341_998153510257216`` + * ``111599105530674:195181727490727:10102446236688861:10205257726909910_195198790822354`` Background: