Restructure the docs, a lot

docs/01_general.rst

@@ -95,6 +95,7 @@ manually (or persist objects, not just dicts).
 
 There are convenience functions available for fetching the previous and next page of
 a paginated request as well as for fetching all pages starting from a first page.
+For details, see `fetch_next()`_, `fetch_previous()`_. and `fetch_remaining()`_.
 
 IDs and unpacking
 -----------------

docs/04_auth.rst

@@ -1,5 +1,5 @@
-App registration and user authentication
-========================================
+App registration, authentication and preferences
+================================================
 .. py:module:: mastodon
 .. py:class: Mastodon
 
@@ -20,12 +20,13 @@ once, and then persist your client id and secret. A convenient method
 for this is provided by the functions dealing with registering the app,
 logging in and the Mastodon classes constructor.
 
-To talk to an instance different from the flagship instance, specify
-the api_base_url (usually, just the URL of the instance, i.e.
-https://mastodon.social/ for the flagship instance). If no protocol
-is specified, Mastodon.py defaults to https.
-
+App registration and information
+--------------------------------
 .. automethod:: Mastodon.create_app
+.. automethod:: Mastodon.app_verify_credentials
+
+Authentication
+--------------    
 .. automethod:: Mastodon.__init__
 .. _log_in():
 .. automethod:: Mastodon.log_in
@@ -36,3 +37,7 @@ is specified, Mastodon.py defaults to https.
 .. automethod:: Mastodon.revoke_access_token
 .. automethod:: Mastodon.create_account
 .. automethod:: Mastodon.email_resend_confirmation
+
+User preferences
+----------------
+.. automethod:: Mastodon.preferences

docs/05_statuses.rst

@@ -0,0 +1,84 @@
+Statuses, media and polls
+=========================
+.. py:module:: mastodon
+.. py:class: Mastodon
+
+Statuses
+--------
+These functions allow you to get information about single statuses and to post and update them, as well as to favourite, bookmark, mute reblog ("boost") and to undo all of those.
+For status pinning, check out TODO and TODO on the accounts page.
+
+Reading
+~~~~~~~
+.. automethod:: Mastodon.status
+.. automethod:: Mastodon.status_context
+.. automethod:: Mastodon.status_reblogged_by
+.. automethod:: Mastodon.status_favourited_by
+.. automethod:: Mastodon.status_card
+.. automethod:: Mastodon.status_history
+.. automethod:: Mastodon.status_source
+
+.. automethod:: Mastodon.favourites
+
+.. automethod:: Mastodon.bookmarks
+
+Writing
+~~~~~~~
+.. _status_post():
+.. automethod:: Mastodon.status_post
+.. automethod:: Mastodon.status_reply
+.. automethod:: Mastodon.toot
+.. _make_poll():
+.. automethod:: Mastodon.make_poll
+
+.. automethod:: Mastodon.status_reblog
+.. automethod:: Mastodon.status_unreblog
+
+.. automethod:: Mastodon.status_favourite
+.. automethod:: Mastodon.status_unfavourite
+
+.. automethod:: Mastodon.status_mute
+.. automethod:: Mastodon.status_unmute
+
+.. automethod:: Mastodon.status_bookmark
+.. automethod:: Mastodon.status_unbookmark
+
+.. automethod:: Mastodon.status_delete
+.. _status_update():    
+.. automethod:: Mastodon.status_update
+
+Scheduled statuses
+------------------
+These functions allow you to get information about scheduled statuses and to update scheduled statuses that already exist.
+To create new scheduled statuses, use `status_post()`_ with the `scheduled_at` parameter.
+
+Reading
+~~~~~~~
+.. automethod:: Mastodon.scheduled_statuses
+.. automethod:: Mastodon.scheduled_status
+
+Writing
+~~~~~~~
+.. automethod:: Mastodon.scheduled_status_update
+.. automethod:: Mastodon.scheduled_status_delete
+
+Media
+-----
+This function allows you to upload media to Mastodon and update media uploads.
+The returned media IDs (Up to 4 at the same time on a default configuration Mastodon instance) can then be used with post_status to attach media to statuses.
+
+.. _media_post():
+.. automethod:: Mastodon.media_post
+.. automethod:: Mastodon.media_update
+
+Polls
+-----
+This function allows you to get and refresh information about polls as well as to vote in polls
+
+Reading
+~~~~~~~
+.. automethod:: Mastodon.poll
+
+Writing
+~~~~~~~
+.. automethod:: Mastodon.poll_vote

docs/06_accounts.rst

@@ -0,0 +1,114 @@
+Accounts, relationships and lists
+=================================
+.. py:module:: mastodon
+.. py:class: Mastodon
+
+Accounts
+--------
+These functions allow you to get information about accounts and associated data as well as update that data - profile data (incuding pinned statuses and endorsements) for the logged in users account, and notes for everyone else
+
+Reading
+~~~~~~~~
+.. automethod:: Mastodon.account_verify_credentials
+.. automethod:: Mastodon.me
+
+.. automethod:: Mastodon.account
+.. automethod:: Mastodon.account_search
+.. automethod:: Mastodon.account_lookup
+
+.. automethod:: Mastodon.featured_tags
+.. automethod:: Mastodon.featured_tag_suggestions
+.. automethod:: Mastodon.account_featured_tags
+
+.. automethod:: Mastodon.endorsements
+
+.. automethod:: Mastodon.account_statuses
+.. automethod:: Mastodon.account_following
+.. automethod:: Mastodon.account_familiar_followers
+
+.. automethod:: Mastodon.account_lists
+
+Writing
+~~~~~~~
+.. automethod:: Mastodon.account_update_credentials
+
+.. automethod:: Mastodon.account_pin
+.. automethod:: Mastodon.account_unpin
+
+.. automethod:: Mastodon.account_note_set
+
+.. automethod:: Mastodon.featured_tag_create
+.. automethod:: Mastodon.featured_tag_delete
+
+.. _status_pin():
+.. automethod:: Mastodon.status_pin
+.. _status_unpin():    
+.. automethod:: Mastodon.status_unpin
+
+Following and followers
+-----------------------
+These functions allow you to get information about the logged in users followers and users that the logged in users follows as well as follow requests and follow suggestions, and to
+manage that data - most importantly, follow and unfollow users.
+
+Reading
+~~~~~~~
+.. automethod:: Mastodon.account_followers
+.. automethod:: Mastodon.account_relationships
+.. automethod:: Mastodon.follows
+
+.. automethod:: Mastodon.follow_requests
+
+.. automethod:: Mastodon.suggestions
+
+Writing
+~~~~~~~
+.. _account_follow():
+.. automethod:: Mastodon.account_follow
+.. automethod:: Mastodon.account_unfollow
+
+.. automethod:: Mastodon.follow_request_authorize
+.. automethod:: Mastodon.follow_request_reject
+
+.. automethod:: Mastodon.suggestion_delete
+
+Mutes and blocks
+----------------
+These functions allow you to get information about accounts and domains that are muted or blocked by the logged in user, and to block and mute users and domains
+
+Reading
+~~~~~~~
+.. automethod:: Mastodon.mutes
+.. automethod:: Mastodon.blocks
+.. automethod:: Mastodon.domain_blocks
+
+Writing
+~~~~~~~
+.. automethod:: Mastodon.account_mute
+.. automethod:: Mastodon.account_unmute
+
+.. automethod:: Mastodon.account_block
+.. automethod:: Mastodon.account_unblock
+
+.. automethod:: Mastodon.account_remove_from_followers
+
+.. automethod:: Mastodon.domain_block
+.. automethod:: Mastodon.domain_unblock
+
+Lists
+-----
+These functions allow you to view information about lists as well as to create and update them.
+By default, the maximum number of lists for a user is 50.
+
+Reading
+~~~~~~~
+.. automethod:: Mastodon.lists
+.. automethod:: Mastodon.list
+.. automethod:: Mastodon.list_accounts
+
+Writing
+~~~~~~~
+.. automethod:: Mastodon.list_create
+.. automethod:: Mastodon.list_update
+.. automethod:: Mastodon.list_delete
+.. automethod:: Mastodon.list_accounts_add
+.. automethod:: Mastodon.list_accounts_delete

docs/07_timelines.rst

@@ -0,0 +1,20 @@
+Reading data: Timelines
+=======================
+.. py:module:: mastodon
+.. py:class: Mastodon
+
+These functions allow you to access the timelines a logged in
+user could see, as well as hashtag timelines and the public (federated)
+and local timelines. For the public, local and hashtag timelines,
+access is allowed even when not authenticated if the instance admin has enabled this functionality.
+
+.. _timeline():
+.. automethod:: Mastodon.timeline
+.. automethod:: Mastodon.timeline_home
+.. automethod:: Mastodon.timeline_local
+.. _timeline_public():
+.. automethod:: Mastodon.timeline_public
+.. _timeline_hashtag():
+.. automethod:: Mastodon.timeline_hashtag
+.. automethod:: Mastodon.timeline_list
+.. automethod:: Mastodon.conversations

docs/08_instances.rst

@@ -0,0 +1,58 @@
+Instance-wide data and search
+=============================
+.. py:module:: mastodon
+.. py:class: Mastodon
+
+Instance information
+--------------------
+These functions allow you to fetch information associated with the
+current instance as well as data from the instance-wide profile directory.
+
+.. _instance():
+.. automethod:: Mastodon.instance
+.. automethod:: Mastodon.instance_activity
+.. automethod:: Mastodon.instance_peers
+.. automethod:: Mastodon.instance_health
+.. automethod:: Mastodon.instance_nodeinfo
+.. automethod:: Mastodon.instance_rules
+
+Profile directory
+~~~~~~~~~~~~~~~~~
+.. automethod:: Mastodon.directory
+
+Emoji
+~~~~~
+.. automethod:: Mastodon.custom_emojis
+
+Announcements
+-------------
+These functions allow you to fetch announcements, mark annoucements read and modify reactions.
+
+Reading
+~~~~~~~
+.. automethod:: Mastodon.announcements
+
+Writing
+~~~~~~~
+.. automethod:: Mastodon.announcement_dismiss
+.. automethod:: Mastodon.announcement_reaction_create
+.. automethod:: Mastodon.announcement_reaction_delete
+
+Trends
+------
+These functions, when enabled, allow you to fetch trending tags, statuses and links.
+
+.. _trending_tags():
+.. automethod:: Mastodon.trending_tags
+.. _trending_statuses():
+.. automethod:: Mastodon.trending_statuses
+.. _trending_links():    
+.. automethod:: Mastodon.trending_links
+.. automethod:: Mastodon.trends
+
+Search
+------
+These functions allow you to search for users, tags and, when enabled, full text, by default within your own posts and those you have interacted with.
+
+.. automethod:: Mastodon.search
+.. automethod:: Mastodon.search_v2

docs/09_notifications.rst

@@ -0,0 +1,61 @@
+Notifications and filtering
+===========================
+.. py:module:: mastodon
+.. py:class: Mastodon
+
+Notifications
+-------------
+This function allows you to get information about a user's notifications as well as to clear all or some notifications and to mark conversations as read.
+
+Reading
+~~~~~~~
+.. automethod:: Mastodon.notifications
+
+Writing
+~~~~~~~
+.. automethod:: Mastodon.notifications_clear
+.. automethod:: Mastodon.notifications_dismiss
+.. automethod:: Mastodon.conversations_read
+
+
+Keyword filters
+---------------
+These functions allow you to get information about keyword filters as well as to create and update filters.
+
+**Very Important Note: The filtering system was revised in 4.0.0. This means that these functions will now not work anymore if an instance is on Mastodon 4.0.0 or above.
+When updating Mastodon.py for 4.0.0, we'll make an effort to emulate old behaviour, but this will not always be possible. Consider these methods deprecated, for now.**
+
+Reading
+~~~~~~~
+.. automethod:: Mastodon.filters
+.. automethod:: Mastodon.filter
+.. automethod:: Mastodon.filters_apply
+
+Writing
+~~~~~~~
+.. automethod:: Mastodon.filter_create
+.. automethod:: Mastodon.filter_update
+.. automethod:: Mastodon.filter_delete
+
+Push notifications
+------------------
+Mastodon supports the delivery of notifications via webpush.
+
+These functions allow you to manage webpush subscriptions and to decrypt received
+pushes. Note that the intended setup is not Mastodon pushing directly to a user's client -
+the push endpoint should usually be a relay server that then takes care of delivering the
+(encrypted) push to the end user via some mechanism, where it can then be decrypted and
+displayed.
+
+Mastodon allows an application to have one webpush subscription per user at a time.
+
+All crypto utilities require Mastodon.py's optional "webpush" feature dependencies
+(specifically, the "cryptography" and "http_ece" packages).
+
+.. automethod:: Mastodon.push_subscription
+.. automethod:: Mastodon.push_subscription_set
+.. automethod:: Mastodon.push_subscription_update
+
+.. _push_subscription_generate_keys():
+.. automethod:: Mastodon.push_subscription_generate_keys
+.. automethod:: Mastodon.push_subscription_decrypt_push