OPML import/export user guide, screenshots, and changelog. #165

Author: lemon24

CHANGES.rst

@@ -11,9 +11,10 @@ Version 3.23
 
 Unreleased
 
-* Add basic support for OPML subscription list import/export:
-  :mod:`reader.opml`.
-  (:issue:`165`)
+* Add support for :ref:`opml`. (:issue:`165`)
+
+  * Add support for import / export in the web app; :ref:`screenshots <screenshots-import>`.
+
 
 * Deprecate the :func:`~reader.utils.archive_entries` ``feed_user_title`` argument.
 

docs/app.rst

@@ -62,6 +62,18 @@ Screenshots
 
     article view (light mode)
 
+.. _screenshots-import:
+
+.. figure:: screenshots/import-select.png
+    :width: 240px
+
+    import feeds (select)
+
+.. figure:: screenshots/import-result.png
+    :width: 240px
+
+    import feeds (result)
+
 
 
 Serving the web app

docs/dev.rst

@@ -32,7 +32,6 @@ in my spare time,
 but I will prioritize supporting :doc:`contributors <contributing>`
 (discussions, reviews and so on).
 
-* OPML support, :issue:`165`
 * :ref:`deleting entries <deleting entries>`
 
   * archiving important entries of deleted feeds, :issue:`290`

docs/guide.rst

@@ -705,35 +705,32 @@ you can delete entries using the low-level
 
 
 
-.. _pagination:
+.. _opml:
 
-Pagination
-----------
+OPML import / export
+--------------------
 
-:meth:`~Reader.get_feeds`, :meth:`~Reader.get_entries`,
-and :meth:`~Reader.search_entries`
-can be used in a paginated fashion.
+You can import and export feeds from and to an `OPML subscription list`_
+by using the :meth:`~Reader.import_feeds`
+and :meth:`~Reader.export_feeds` methods::
 
-The ``limit`` argument allows limiting the number of results returned;
-the ``starting_after`` argument allows skipping results until after
-a specific one.
-
-To get the first page, use only ``limit``::
-
-    >>> for entry in reader.get_entries(limit=2):
-    ...     print(entry.title)
+    >>> export = reader.export_feeds()
+    >>> export.filename
+    'reader-feeds-2026-04-24-10-00-00.opml'
+    >>> with open(export.filename, 'wb') as f:
+    ...     f.write(export.content)
     ...
-    H.I. #136: Dog Bingo
-    H.I. #135: Place Your Bets
+    >>> # with another reader instance
+    >>> reader = make_reader(':memory:')
+    >>> with open(export.filename, 'rb') as f:
+    ...     reader.import_feeds(f)
 
-To get the next page, use the last result from a call as
-``starting_after`` in the next call::
+For more detailed control over which feeds are imported,
+see :meth:`~Reader.import_feeds_iter` and the :mod:`reader.opml` module.
 
-    >>> for entry in reader.get_entries(limit=2, starting_after=entry):
-    ...     print(entry.title)
-    ...
-    # H.I. 134: Boxing Day
-    Star Wars: The Rise of Skywalker, Hello Internet Christmas Special
+.. _OPML subscription list: https://opml.org/spec2.opml#subscriptionLists
+
+.. versionadded:: 3.23
 
 
 
@@ -831,6 +828,38 @@ Some examples of how this is useful:
 
 
 
+.. _pagination:
+
+Pagination
+----------
+
+:meth:`~Reader.get_feeds`, :meth:`~Reader.get_entries`,
+and :meth:`~Reader.search_entries`
+can be used in a paginated fashion.
+
+The ``limit`` argument allows limiting the number of results returned;
+the ``starting_after`` argument allows skipping results until after
+a specific one.
+
+To get the first page, use only ``limit``::
+
+    >>> for entry in reader.get_entries(limit=2):
+    ...     print(entry.title)
+    ...
+    H.I. #136: Dog Bingo
+    H.I. #135: Place Your Bets
+
+To get the next page, use the last result from a call as
+``starting_after`` in the next call::
+
+    >>> for entry in reader.get_entries(limit=2, starting_after=entry):
+    ...     print(entry.title)
+    ...
+    # H.I. 134: Boxing Day
+    Star Wars: The Rise of Skywalker, Hello Internet Christmas Special
+
+
+
 .. _reserved names:
 
 Reserved names