aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorhalcy <halcy@ARARAGI-KUN>2022-11-29 00:50:02 +0200
committerhalcy <halcy@ARARAGI-KUN>2022-11-29 00:50:02 +0200
commit43c7d7ceb8da17954aedee96bd6fb5444a4a728c (patch)
treebb7cdad59a16447841adc15cb047202b47661220 /docs
parentbd3db974d771d753e7732fabe6a050b779c466e2 (diff)
downloadmastodon.py-43c7d7ceb8da17954aedee96bd6fb5444a4a728c.tar.gz
Restructure the docs, a lot
Diffstat (limited to 'docs')
-rw-r--r--docs/01_general.rst1
-rw-r--r--docs/04_auth.rst19
-rw-r--r--docs/05_statuses.rst84
-rw-r--r--docs/06_accounts.rst114
-rw-r--r--docs/07_timelines.rst20
-rw-r--r--docs/08_instances.rst58
-rw-r--r--docs/09_notifications.rst61
-rw-r--r--docs/10_streaming.rst75
-rw-r--r--docs/11_misc.rst36
-rw-r--r--docs/12_utilities.rst22
-rw-r--r--docs/13_admin.rst60
-rw-r--r--docs/14_contributing.rst33
-rw-r--r--docs/15_everything.rst188
-rw-r--r--docs/index.rst23
-rwxr-xr-xdocs/update_everything_page.sh8
15 files changed, 792 insertions, 10 deletions
diff --git a/docs/01_general.rst b/docs/01_general.rst
index e0c3719..556cd63 100644
--- a/docs/01_general.rst
+++ b/docs/01_general.rst
@@ -95,6 +95,7 @@ manually (or persist objects, not just dicts).
95 95
96There are convenience functions available for fetching the previous and next page of 96There are convenience functions available for fetching the previous and next page of
97a paginated request as well as for fetching all pages starting from a first page. 97a paginated request as well as for fetching all pages starting from a first page.
98For details, see `fetch_next()`_, `fetch_previous()`_. and `fetch_remaining()`_.
98 99
99IDs and unpacking 100IDs and unpacking
100----------------- 101-----------------
diff --git a/docs/04_auth.rst b/docs/04_auth.rst
index 1a05603..845ffde 100644
--- a/docs/04_auth.rst
+++ b/docs/04_auth.rst
@@ -1,5 +1,5 @@
1App registration and user authentication 1App registration, authentication and preferences
2======================================== 2================================================
3.. py:module:: mastodon 3.. py:module:: mastodon
4.. py:class: Mastodon 4.. py:class: Mastodon
5 5
@@ -20,12 +20,13 @@ once, and then persist your client id and secret. A convenient method
20for this is provided by the functions dealing with registering the app, 20for this is provided by the functions dealing with registering the app,
21logging in and the Mastodon classes constructor. 21logging in and the Mastodon classes constructor.
22 22
23To talk to an instance different from the flagship instance, specify 23App registration and information
24the api_base_url (usually, just the URL of the instance, i.e. 24--------------------------------
25https://mastodon.social/ for the flagship instance). If no protocol
26is specified, Mastodon.py defaults to https.
27
28.. automethod:: Mastodon.create_app 25.. automethod:: Mastodon.create_app
26.. automethod:: Mastodon.app_verify_credentials
27
28Authentication
29--------------
29.. automethod:: Mastodon.__init__ 30.. automethod:: Mastodon.__init__
30.. _log_in(): 31.. _log_in():
31.. automethod:: Mastodon.log_in 32.. automethod:: Mastodon.log_in
@@ -36,3 +37,7 @@ is specified, Mastodon.py defaults to https.
36.. automethod:: Mastodon.revoke_access_token 37.. automethod:: Mastodon.revoke_access_token
37.. automethod:: Mastodon.create_account 38.. automethod:: Mastodon.create_account
38.. automethod:: Mastodon.email_resend_confirmation 39.. automethod:: Mastodon.email_resend_confirmation
40
41User preferences
42----------------
43.. automethod:: Mastodon.preferences \ No newline at end of file
diff --git a/docs/05_statuses.rst b/docs/05_statuses.rst
new file mode 100644
index 0000000..5615a9f
--- /dev/null
+++ b/docs/05_statuses.rst
@@ -0,0 +1,84 @@
1Statuses, media and polls
2=========================
3.. py:module:: mastodon
4.. py:class: Mastodon
5
6Statuses
7--------
8These 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.
9For status pinning, check out TODO and TODO on the accounts page.
10
11Reading
12~~~~~~~
13.. automethod:: Mastodon.status
14.. automethod:: Mastodon.status_context
15.. automethod:: Mastodon.status_reblogged_by
16.. automethod:: Mastodon.status_favourited_by
17.. automethod:: Mastodon.status_card
18.. automethod:: Mastodon.status_history
19.. automethod:: Mastodon.status_source
20
21.. automethod:: Mastodon.favourites
22
23.. automethod:: Mastodon.bookmarks
24
25Writing
26~~~~~~~
27.. _status_post():
28.. automethod:: Mastodon.status_post
29.. automethod:: Mastodon.status_reply
30.. automethod:: Mastodon.toot
31.. _make_poll():
32.. automethod:: Mastodon.make_poll
33
34.. automethod:: Mastodon.status_reblog
35.. automethod:: Mastodon.status_unreblog
36
37.. automethod:: Mastodon.status_favourite
38.. automethod:: Mastodon.status_unfavourite
39
40.. automethod:: Mastodon.status_mute
41.. automethod:: Mastodon.status_unmute
42
43.. automethod:: Mastodon.status_bookmark
44.. automethod:: Mastodon.status_unbookmark
45
46.. automethod:: Mastodon.status_delete
47.. _status_update():
48.. automethod:: Mastodon.status_update
49
50Scheduled statuses
51------------------
52These functions allow you to get information about scheduled statuses and to update scheduled statuses that already exist.
53To create new scheduled statuses, use `status_post()`_ with the `scheduled_at` parameter.
54
55Reading
56~~~~~~~
57.. automethod:: Mastodon.scheduled_statuses
58.. automethod:: Mastodon.scheduled_status
59
60Writing
61~~~~~~~
62.. automethod:: Mastodon.scheduled_status_update
63.. automethod:: Mastodon.scheduled_status_delete
64
65Media
66-----
67This function allows you to upload media to Mastodon and update media uploads.
68The 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.
69
70.. _media_post():
71.. automethod:: Mastodon.media_post
72.. automethod:: Mastodon.media_update
73
74Polls
75-----
76This function allows you to get and refresh information about polls as well as to vote in polls
77
78Reading
79~~~~~~~
80.. automethod:: Mastodon.poll
81
82Writing
83~~~~~~~
84.. automethod:: Mastodon.poll_vote \ No newline at end of file
diff --git a/docs/06_accounts.rst b/docs/06_accounts.rst
new file mode 100644
index 0000000..7fe37e5
--- /dev/null
+++ b/docs/06_accounts.rst
@@ -0,0 +1,114 @@
1Accounts, relationships and lists
2=================================
3.. py:module:: mastodon
4.. py:class: Mastodon
5
6Accounts
7--------
8These 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
9
10Reading
11~~~~~~~~
12.. automethod:: Mastodon.account_verify_credentials
13.. automethod:: Mastodon.me
14
15.. automethod:: Mastodon.account
16.. automethod:: Mastodon.account_search
17.. automethod:: Mastodon.account_lookup
18
19.. automethod:: Mastodon.featured_tags
20.. automethod:: Mastodon.featured_tag_suggestions
21.. automethod:: Mastodon.account_featured_tags
22
23.. automethod:: Mastodon.endorsements
24
25.. automethod:: Mastodon.account_statuses
26.. automethod:: Mastodon.account_following
27.. automethod:: Mastodon.account_familiar_followers
28
29.. automethod:: Mastodon.account_lists
30
31Writing
32~~~~~~~
33.. automethod:: Mastodon.account_update_credentials
34
35.. automethod:: Mastodon.account_pin
36.. automethod:: Mastodon.account_unpin
37
38.. automethod:: Mastodon.account_note_set
39
40.. automethod:: Mastodon.featured_tag_create
41.. automethod:: Mastodon.featured_tag_delete
42
43.. _status_pin():
44.. automethod:: Mastodon.status_pin
45.. _status_unpin():
46.. automethod:: Mastodon.status_unpin
47
48Following and followers
49-----------------------
50These 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
51manage that data - most importantly, follow and unfollow users.
52
53Reading
54~~~~~~~
55.. automethod:: Mastodon.account_followers
56.. automethod:: Mastodon.account_relationships
57.. automethod:: Mastodon.follows
58
59.. automethod:: Mastodon.follow_requests
60
61.. automethod:: Mastodon.suggestions
62
63Writing
64~~~~~~~
65.. _account_follow():
66.. automethod:: Mastodon.account_follow
67.. automethod:: Mastodon.account_unfollow
68
69.. automethod:: Mastodon.follow_request_authorize
70.. automethod:: Mastodon.follow_request_reject
71
72.. automethod:: Mastodon.suggestion_delete
73
74Mutes and blocks
75----------------
76These 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
77
78Reading
79~~~~~~~
80.. automethod:: Mastodon.mutes
81.. automethod:: Mastodon.blocks
82.. automethod:: Mastodon.domain_blocks
83
84Writing
85~~~~~~~
86.. automethod:: Mastodon.account_mute
87.. automethod:: Mastodon.account_unmute
88
89.. automethod:: Mastodon.account_block
90.. automethod:: Mastodon.account_unblock
91
92.. automethod:: Mastodon.account_remove_from_followers
93
94.. automethod:: Mastodon.domain_block
95.. automethod:: Mastodon.domain_unblock
96
97Lists
98-----
99These functions allow you to view information about lists as well as to create and update them.
100By default, the maximum number of lists for a user is 50.
101
102Reading
103~~~~~~~
104.. automethod:: Mastodon.lists
105.. automethod:: Mastodon.list
106.. automethod:: Mastodon.list_accounts
107
108Writing
109~~~~~~~
110.. automethod:: Mastodon.list_create
111.. automethod:: Mastodon.list_update
112.. automethod:: Mastodon.list_delete
113.. automethod:: Mastodon.list_accounts_add
114.. automethod:: Mastodon.list_accounts_delete
diff --git a/docs/07_timelines.rst b/docs/07_timelines.rst
new file mode 100644
index 0000000..8a82d3b
--- /dev/null
+++ b/docs/07_timelines.rst
@@ -0,0 +1,20 @@
1Reading data: Timelines
2=======================
3.. py:module:: mastodon
4.. py:class: Mastodon
5
6These functions allow you to access the timelines a logged in
7user could see, as well as hashtag timelines and the public (federated)
8and local timelines. For the public, local and hashtag timelines,
9access is allowed even when not authenticated if the instance admin has enabled this functionality.
10
11.. _timeline():
12.. automethod:: Mastodon.timeline
13.. automethod:: Mastodon.timeline_home
14.. automethod:: Mastodon.timeline_local
15.. _timeline_public():
16.. automethod:: Mastodon.timeline_public
17.. _timeline_hashtag():
18.. automethod:: Mastodon.timeline_hashtag
19.. automethod:: Mastodon.timeline_list
20.. automethod:: Mastodon.conversations \ No newline at end of file
diff --git a/docs/08_instances.rst b/docs/08_instances.rst
new file mode 100644
index 0000000..35b3c5d
--- /dev/null
+++ b/docs/08_instances.rst
@@ -0,0 +1,58 @@
1Instance-wide data and search
2=============================
3.. py:module:: mastodon
4.. py:class: Mastodon
5
6Instance information
7--------------------
8These functions allow you to fetch information associated with the
9current instance as well as data from the instance-wide profile directory.
10
11.. _instance():
12.. automethod:: Mastodon.instance
13.. automethod:: Mastodon.instance_activity
14.. automethod:: Mastodon.instance_peers
15.. automethod:: Mastodon.instance_health
16.. automethod:: Mastodon.instance_nodeinfo
17.. automethod:: Mastodon.instance_rules
18
19Profile directory
20~~~~~~~~~~~~~~~~~
21.. automethod:: Mastodon.directory
22
23Emoji
24~~~~~
25.. automethod:: Mastodon.custom_emojis
26
27Announcements
28-------------
29These functions allow you to fetch announcements, mark annoucements read and modify reactions.
30
31Reading
32~~~~~~~
33.. automethod:: Mastodon.announcements
34
35Writing
36~~~~~~~
37.. automethod:: Mastodon.announcement_dismiss
38.. automethod:: Mastodon.announcement_reaction_create
39.. automethod:: Mastodon.announcement_reaction_delete
40
41Trends
42------
43These functions, when enabled, allow you to fetch trending tags, statuses and links.
44
45.. _trending_tags():
46.. automethod:: Mastodon.trending_tags
47.. _trending_statuses():
48.. automethod:: Mastodon.trending_statuses
49.. _trending_links():
50.. automethod:: Mastodon.trending_links
51.. automethod:: Mastodon.trends
52
53Search
54------
55These 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.
56
57.. automethod:: Mastodon.search
58.. automethod:: Mastodon.search_v2
diff --git a/docs/09_notifications.rst b/docs/09_notifications.rst
new file mode 100644
index 0000000..cc45fdb
--- /dev/null
+++ b/docs/09_notifications.rst
@@ -0,0 +1,61 @@
1Notifications and filtering
2===========================
3.. py:module:: mastodon
4.. py:class: Mastodon
5
6Notifications
7-------------
8This 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.
9
10Reading
11~~~~~~~
12.. automethod:: Mastodon.notifications
13
14Writing
15~~~~~~~
16.. automethod:: Mastodon.notifications_clear
17.. automethod:: Mastodon.notifications_dismiss
18.. automethod:: Mastodon.conversations_read
19
20
21Keyword filters
22---------------
23These functions allow you to get information about keyword filters as well as to create and update filters.
24
25**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.
26When 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.**
27
28Reading
29~~~~~~~
30.. automethod:: Mastodon.filters
31.. automethod:: Mastodon.filter
32.. automethod:: Mastodon.filters_apply
33
34Writing
35~~~~~~~
36.. automethod:: Mastodon.filter_create
37.. automethod:: Mastodon.filter_update
38.. automethod:: Mastodon.filter_delete
39
40Push notifications
41------------------
42Mastodon supports the delivery of notifications via webpush.
43
44These functions allow you to manage webpush subscriptions and to decrypt received
45pushes. Note that the intended setup is not Mastodon pushing directly to a user's client -
46the push endpoint should usually be a relay server that then takes care of delivering the
47(encrypted) push to the end user via some mechanism, where it can then be decrypted and
48displayed.
49
50Mastodon allows an application to have one webpush subscription per user at a time.
51
52All crypto utilities require Mastodon.py's optional "webpush" feature dependencies
53(specifically, the "cryptography" and "http_ece" packages).
54
55.. automethod:: Mastodon.push_subscription
56.. automethod:: Mastodon.push_subscription_set
57.. automethod:: Mastodon.push_subscription_update
58
59.. _push_subscription_generate_keys():
60.. automethod:: Mastodon.push_subscription_generate_keys
61.. automethod:: Mastodon.push_subscription_decrypt_push
diff --git a/docs/10_streaming.rst b/docs/10_streaming.rst
new file mode 100644
index 0000000..7a7723b
--- /dev/null
+++ b/docs/10_streaming.rst
@@ -0,0 +1,75 @@
1Streaming
2=========
3.. py:module:: mastodon
4.. py:class: Mastodon
5
6These functions allow access to the streaming API. For the public, local and hashtag streams,
7access is generally possible without authenticating.
8
9If `run_async` is False, these methods block forever (or until an error is encountered).
10
11If `run_async` is True, the listener will listen on another thread and these methods
12will return a handle corresponding to the open connection. If, in addition, `reconnect_async` is True,
13the thread will attempt to reconnect to the streaming API if any errors are encountered, waiting
14`reconnect_async_wait_sec` seconds between reconnection attempts. Note that no effort is made
15to "catch up" - events created while the connection is broken will not be received. If you need to make
16sure to get absolutely all notifications / deletes / toots, you will have to do that manually, e.g.
17using the `on_abort` handler to fill in events since the last received one and then reconnecting.
18Both `run_async` and `reconnect_async` default to false, and you'll have to set each to true
19separately to get the behaviour described above.
20
21The connection may be closed at any time by calling the handles close() method. The
22current status of the handler thread can be checked with the handles is_alive() function,
23and the streaming status can be checked by calling is_receiving().
24
25The streaming functions take instances of `StreamListener` as the `listener` parameter.
26A `CallbackStreamListener` class that allows you to specify function callbacks
27directly is included for convenience.
28
29For new well-known events implement the streaming function in `StreamListener` or `CallbackStreamListener`.
30The function name is `on_` + the event name. If the event name contains dots, they are replaced with
31underscored, e.g. for an event called 'status.update' the listener function should be named `on_status_update`.
32
33It may be that future Mastodon versions will come with completely new (unknown) event names.
34If you want to do something when such an event is received, override the listener function `on_unknown_event`.
35This has an additional parameter `name` which informs about the name of the event. `unknown_event` contains the
36content of the event. Alternatively, a callback function can be passed in the `unknown_event_handler` parameter
37in the `CallbackStreamListener` constructor.
38
39Note that the `unknown_event` handler is *not* guaranteed to receive events once they have been implemented.
40Events will only go to this handler temporarily, while Mastodon.py has not been updated. Changes to what events
41do and do not go into the handler will not be considered a breaking change. If you want to handle a new event whose
42name you _do_ know, define an appropriate handler in your StreamListener, which will work even if it is not listed here.
43
44When in not-async mode or async mode without async_reconnect, the stream functions may raise
45various exceptions: `MastodonMalformedEventError` if a received event cannot be parsed and
46`MastodonNetworkError` if any connection problems occur.
47
48Mastodon.py currently does not support websocket based, multiplexed streams, but might in the future.
49
50Stream endpoints
51----------------
52.. automethod:: Mastodon.stream_user
53.. automethod:: Mastodon.stream_public
54.. automethod:: Mastodon.stream_local
55.. automethod:: Mastodon.stream_hashtag
56.. automethod:: Mastodon.stream_list
57.. automethod:: Mastodon.stream_healthy
58
59StreamListener
60--------------
61
62.. autoclass:: StreamListener
63.. automethod:: StreamListener.on_update
64.. automethod:: StreamListener.on_notification
65.. automethod:: StreamListener.on_delete
66.. automethod:: StreamListener.on_conversation
67.. automethod:: StreamListener.on_status_update
68.. automethod:: StreamListener.on_unknown_event
69.. automethod:: StreamListener.on_abort
70.. automethod:: StreamListener.handle_heartbeat
71
72CallbackStreamListener
73~~~~~~~~~~~~~~~~~~~~~~
74
75.. autoclass:: CallbackStreamListener \ No newline at end of file
diff --git a/docs/11_misc.rst b/docs/11_misc.rst
new file mode 100644
index 0000000..a85d518
--- /dev/null
+++ b/docs/11_misc.rst
@@ -0,0 +1,36 @@
1Misc: Markers, reports
2======================
3.. py:module:: mastodon
4.. py:class: Mastodon
5
6Markers
7-------
8These functions allow you to interact with the timeline "last read" markers,
9to allow for persisting where the user was reading a timeline between sessions
10and clients / devices.
11
12
13Reading
14~~~~~~~
15.. automethod:: Mastodon.markers_get
16
17Writing
18~~~~~~~
19.. automethod:: Mastodon.markers_set
20
21Reports
22-------
23
24Reading
25~~~~~~~
26In Mastodon versions before 2.5.0 this function allowed for the retrieval
27of reports filed by the logged in user. It has since been removed.
28
29.. automethod:: Mastodon.reports
30
31Writing
32~~~~~~~
33This function allows you to report a user to the instance moderators as well as to
34the users home instance.
35
36.. automethod:: Mastodon.report \ No newline at end of file
diff --git a/docs/12_utilities.rst b/docs/12_utilities.rst
new file mode 100644
index 0000000..9666578
--- /dev/null
+++ b/docs/12_utilities.rst
@@ -0,0 +1,22 @@
1Utility: Pagination and Blurhash
2================================
3.. py:module:: mastodon
4.. py:class: Mastodon
5
6Pagination
7----------
8These functions allow for convenient retrieval of paginated data.
9
10.. _fetch_next():
11.. automethod:: Mastodon.fetch_next
12.. _fetch_previous():
13.. automethod:: Mastodon.fetch_previous
14.. _fetch_remaining():
15.. automethod:: Mastodon.fetch_remaining
16
17Blurhash decoding
18-----------------
19This function allows for easy basic decoding of blurhash strings to images.
20This requires Mastodon.pys optional "blurhash" feature dependencies.
21
22.. automethod:: Mastodon.decode_blurhash
diff --git a/docs/13_admin.rst b/docs/13_admin.rst
new file mode 100644
index 0000000..1c97d2c
--- /dev/null
+++ b/docs/13_admin.rst
@@ -0,0 +1,60 @@
1Administration and moderation
2=============================
3.. py:module:: mastodon
4.. py:class: Mastodon
5
6These functions allow you to perform moderation actions on users and generally
7process reports using the API. To do this, you need access to the "admin:read" and/or
8"admin:write" scopes or their more granular variants (both for the application and the
9access token), as well as at least moderator access. Mastodon.py will not request these
10by default, as that would be very dangerous.
11
12BIG WARNING: TREAT ANY ACCESS TOKENS THAT HAVE ADMIN CREDENTIALS AS EXTREMELY, MASSIVELY
13SENSITIVE DATA AND MAKE EXTRA SURE TO REVOKE THEM AFTER TESTING, NOT LET THEM SIT IN FILES
14SOMEWHERE, TRACK WHICH ARE ACTIVE, ET CETERA. ANY EXPOSURE OF SUCH ACCESS TOKENS MEANS YOU
15EXPOSE THE PERSONAL DATA OF ALL YOUR USERS TO WHOEVER HAS THESE TOKENS. TREAT THEM WITH
16EXTREME CARE.
17
18This is not to say that you should not treat access tokens from admin accounts that do not
19have admin: scopes attached with a lot of care, but be extra careful with those that do.
20
21Accounts
22--------
23.. automethod:: Mastodon.admin_accounts_v2
24.. automethod:: Mastodon.admin_accounts
25.. automethod:: Mastodon.admin_accounts_v1
26.. automethod:: Mastodon.admin_account
27.. automethod:: Mastodon.admin_account_enable
28.. automethod:: Mastodon.admin_account_approve
29.. automethod:: Mastodon.admin_account_reject
30.. automethod:: Mastodon.admin_account_unsilence
31.. automethod:: Mastodon.admin_account_unsuspend
32.. automethod:: Mastodon.admin_account_moderate
33
34Reports
35-------
36.. automethod:: Mastodon.admin_reports
37.. automethod:: Mastodon.admin_report
38.. automethod:: Mastodon.admin_report_assign
39.. automethod:: Mastodon.admin_report_unassign
40.. automethod:: Mastodon.admin_report_reopen
41.. automethod:: Mastodon.admin_report_resolve
42
43Trends
44------
45.. automethod:: Mastodon.admin_trending_tags
46.. automethod:: Mastodon.admin_trending_statuses
47.. automethod:: Mastodon.admin_trending_links
48.. automethod:: Mastodon.admin_domain_blocks
49
50Federation
51----------
52.. automethod:: Mastodon.admin_create_domain_block
53.. automethod:: Mastodon.admin_update_domain_block
54.. automethod:: Mastodon.admin_delete_domain_block
55
56Moderation actions
57------------------
58.. automethod:: Mastodon.admin_measures
59.. automethod:: Mastodon.admin_dimensions
60.. automethod:: Mastodon.admin_retention \ No newline at end of file
diff --git a/docs/14_contributing.rst b/docs/14_contributing.rst
new file mode 100644
index 0000000..7f743b0
--- /dev/null
+++ b/docs/14_contributing.rst
@@ -0,0 +1,33 @@
1Contributing
2============
3
4How to contribute
5-----------------
6
7Mastodon.py is incomplete a lot of the time because Mastodon has a very rich API with many functions, not all of which are implemented here.
8Even when it is complete for a given Mastodon API version, there are forks and other Mastodon-API-compatible software that implement their own methods which Mastodon.py could in principle support.
9And even when all of that work is done, it will inevitably have bugs, or places where the library could be made easier to use (which, really, are also bugs), missing tests that could catch bugs quicker, tooling to make updating everything faster, et cetera.
10
11You can help get more of this done, and you should! This can take many forms: If you notice somtehing is missing, broken or confusing:
12
13* You could file an issue on github, either with or without suggestions for how to fix the issue: https://github.com/halcy/Mastodon.py/issues
14* You could, after filing an issue, do a PR that fixes that issue
15* You could even just vaguely complain in my (https://icosahedron.website/@halcy) general direction on Mastodon
16
17All of these help immensely, even if it's just "hey, I don't really get why X isn't working". We can't make the library better if we don't know what the actual issues people
18have are, so while I'm not going to implement every suggestion and do have some ideas of what does and does not make a good library, your feedback is, in fact, extremely valuable
19and welcome.
20
21If you're looking for some "starter issues" to address: Currently, we don't have support for much of any of the new 4.0.0 API endpoints implemented. Pick one and have a go,
22especially from the admin API. Tests are somewhat annoying to set up, as they need to run against a live mastodon instance - great if you can write them, but feel free to
23skip out on them, too, or just write them "in the dry" without actually running them and leaving that for someone else.
24
25Tests
26-----
27Mastodon.py has an extensive suite of tests. The purpose of these is twofold:
28
29* Make sure nothing is broken and that there aren't any regressions
30* Where the official docs are unclear, verify assumptions we make about the Mastodon API and document the results
31
32The tests use pytest and pytest-vcr so that they can be ran even without a mastodon server, but new tests require
33setting up a mastodon dev server. Further documentation can be found in the "tests" directory in the repository. \ No newline at end of file
diff --git a/docs/15_everything.rst b/docs/15_everything.rst
new file mode 100644
index 0000000..84ddbbe
--- /dev/null
+++ b/docs/15_everything.rst
@@ -0,0 +1,188 @@
1Every function on a huge CTRL-F-able page
2=========================================
3.. py:module:: mastodon
4.. py:class: Mastodon
5
6.. automethod:: Mastodon.retrieve_mastodon_version
7.. automethod:: Mastodon.verify_minimum_version
8.. automethod:: Mastodon.create_app
9.. automethod:: Mastodon.app_verify_credentials
10.. automethod:: Mastodon.__init__
11.. automethod:: Mastodon.log_in
12.. automethod:: Mastodon.auth_request_url
13.. automethod:: Mastodon.set_language
14.. automethod:: Mastodon.revoke_access_token
15.. automethod:: Mastodon.create_account
16.. automethod:: Mastodon.email_resend_confirmation
17.. automethod:: Mastodon.preferencesStatuses, media and polls
18.. automethod:: Mastodon.status
19.. automethod:: Mastodon.status_context
20.. automethod:: Mastodon.status_reblogged_by
21.. automethod:: Mastodon.status_favourited_by
22.. automethod:: Mastodon.status_card
23.. automethod:: Mastodon.status_history
24.. automethod:: Mastodon.status_source
25.. automethod:: Mastodon.favourites
26.. automethod:: Mastodon.bookmarks
27.. automethod:: Mastodon.status_post
28.. automethod:: Mastodon.status_reply
29.. automethod:: Mastodon.toot
30.. automethod:: Mastodon.make_poll
31.. automethod:: Mastodon.status_reblog
32.. automethod:: Mastodon.status_unreblog
33.. automethod:: Mastodon.status_favourite
34.. automethod:: Mastodon.status_unfavourite
35.. automethod:: Mastodon.status_mute
36.. automethod:: Mastodon.status_unmute
37.. automethod:: Mastodon.status_bookmark
38.. automethod:: Mastodon.status_unbookmark
39.. automethod:: Mastodon.status_delete
40.. automethod:: Mastodon.status_update
41.. automethod:: Mastodon.scheduled_statuses
42.. automethod:: Mastodon.scheduled_status
43.. automethod:: Mastodon.scheduled_status_update
44.. automethod:: Mastodon.scheduled_status_delete
45.. automethod:: Mastodon.media_post
46.. automethod:: Mastodon.media_update
47.. automethod:: Mastodon.poll
48.. automethod:: Mastodon.poll_voteAccounts, relationships and lists
49.. automethod:: Mastodon.account_verify_credentials
50.. automethod:: Mastodon.me
51.. automethod:: Mastodon.account
52.. automethod:: Mastodon.account_search
53.. automethod:: Mastodon.account_lookup
54.. automethod:: Mastodon.featured_tags
55.. automethod:: Mastodon.featured_tag_suggestions
56.. automethod:: Mastodon.account_featured_tags
57.. automethod:: Mastodon.endorsements
58.. automethod:: Mastodon.account_statuses
59.. automethod:: Mastodon.account_following
60.. automethod:: Mastodon.account_familiar_followers
61.. automethod:: Mastodon.account_lists
62.. automethod:: Mastodon.account_update_credentials
63.. automethod:: Mastodon.account_pin
64.. automethod:: Mastodon.account_unpin
65.. automethod:: Mastodon.account_note_set
66.. automethod:: Mastodon.featured_tag_create
67.. automethod:: Mastodon.featured_tag_delete
68.. automethod:: Mastodon.status_pin
69.. automethod:: Mastodon.status_unpin
70.. automethod:: Mastodon.account_followers
71.. automethod:: Mastodon.account_relationships
72.. automethod:: Mastodon.follows
73.. automethod:: Mastodon.follow_requests
74.. automethod:: Mastodon.suggestions
75.. automethod:: Mastodon.account_follow
76.. automethod:: Mastodon.account_unfollow
77.. automethod:: Mastodon.follow_request_authorize
78.. automethod:: Mastodon.follow_request_reject
79.. automethod:: Mastodon.suggestion_delete
80.. automethod:: Mastodon.mutes
81.. automethod:: Mastodon.blocks
82.. automethod:: Mastodon.domain_blocks
83.. automethod:: Mastodon.account_mute
84.. automethod:: Mastodon.account_unmute
85.. automethod:: Mastodon.account_block
86.. automethod:: Mastodon.account_unblock
87.. automethod:: Mastodon.account_remove_from_followers
88.. automethod:: Mastodon.domain_block
89.. automethod:: Mastodon.domain_unblock
90.. automethod:: Mastodon.lists
91.. automethod:: Mastodon.list
92.. automethod:: Mastodon.list_accounts
93.. automethod:: Mastodon.list_create
94.. automethod:: Mastodon.list_update
95.. automethod:: Mastodon.list_delete
96.. automethod:: Mastodon.list_accounts_add
97.. automethod:: Mastodon.list_accounts_delete
98.. automethod:: Mastodon.timeline
99.. automethod:: Mastodon.timeline_home
100.. automethod:: Mastodon.timeline_local
101.. automethod:: Mastodon.timeline_public
102.. automethod:: Mastodon.timeline_hashtag
103.. automethod:: Mastodon.timeline_list
104.. automethod:: Mastodon.conversationsInstance-wide data and search
105.. automethod:: Mastodon.instance
106.. automethod:: Mastodon.instance_activity
107.. automethod:: Mastodon.instance_peers
108.. automethod:: Mastodon.instance_health
109.. automethod:: Mastodon.instance_nodeinfo
110.. automethod:: Mastodon.instance_rules
111.. automethod:: Mastodon.directory
112.. automethod:: Mastodon.custom_emojis
113.. automethod:: Mastodon.announcements
114.. automethod:: Mastodon.announcement_dismiss
115.. automethod:: Mastodon.announcement_reaction_create
116.. automethod:: Mastodon.announcement_reaction_delete
117.. automethod:: Mastodon.trending_tags
118.. automethod:: Mastodon.trending_statuses
119.. automethod:: Mastodon.trending_links
120.. automethod:: Mastodon.trends
121.. automethod:: Mastodon.search
122.. automethod:: Mastodon.search_v2
123.. automethod:: Mastodon.notifications
124.. automethod:: Mastodon.notifications_clear
125.. automethod:: Mastodon.notifications_dismiss
126.. automethod:: Mastodon.conversations_read
127.. automethod:: Mastodon.filters
128.. automethod:: Mastodon.filter
129.. automethod:: Mastodon.filters_apply
130.. automethod:: Mastodon.filter_create
131.. automethod:: Mastodon.filter_update
132.. automethod:: Mastodon.filter_delete
133.. automethod:: Mastodon.push_subscription
134.. automethod:: Mastodon.push_subscription_set
135.. automethod:: Mastodon.push_subscription_update
136.. automethod:: Mastodon.push_subscription_generate_keys
137.. automethod:: Mastodon.push_subscription_decrypt_push
138.. automethod:: Mastodon.stream_user
139.. automethod:: Mastodon.stream_public
140.. automethod:: Mastodon.stream_local
141.. automethod:: Mastodon.stream_hashtag
142.. automethod:: Mastodon.stream_list
143.. automethod:: Mastodon.stream_healthy
144.. autoclass:: StreamListener
145.. automethod:: StreamListener.on_update
146.. automethod:: StreamListener.on_notification
147.. automethod:: StreamListener.on_delete
148.. automethod:: StreamListener.on_conversation
149.. automethod:: StreamListener.on_status_update
150.. automethod:: StreamListener.on_unknown_event
151.. automethod:: StreamListener.on_abort
152.. automethod:: StreamListener.handle_heartbeat
153.. autoclass:: CallbackStreamListenerMisc: Markers, reports
154.. automethod:: Mastodon.markers_get
155.. automethod:: Mastodon.markers_set
156.. automethod:: Mastodon.reports
157.. automethod:: Mastodon.reportUtility: Pagination and Blurhash
158.. automethod:: Mastodon.fetch_next
159.. automethod:: Mastodon.fetch_previous
160.. automethod:: Mastodon.fetch_remaining
161.. automethod:: Mastodon.decode_blurhash
162.. automethod:: Mastodon.admin_accounts_v2
163.. automethod:: Mastodon.admin_accounts
164.. automethod:: Mastodon.admin_accounts_v1
165.. automethod:: Mastodon.admin_account
166.. automethod:: Mastodon.admin_account_enable
167.. automethod:: Mastodon.admin_account_approve
168.. automethod:: Mastodon.admin_account_reject
169.. automethod:: Mastodon.admin_account_unsilence
170.. automethod:: Mastodon.admin_account_unsuspend
171.. automethod:: Mastodon.admin_account_moderate
172.. automethod:: Mastodon.admin_reports
173.. automethod:: Mastodon.admin_report
174.. automethod:: Mastodon.admin_report_assign
175.. automethod:: Mastodon.admin_report_unassign
176.. automethod:: Mastodon.admin_report_reopen
177.. automethod:: Mastodon.admin_report_resolve
178.. automethod:: Mastodon.admin_trending_tags
179.. automethod:: Mastodon.admin_trending_statuses
180.. automethod:: Mastodon.admin_trending_links
181.. automethod:: Mastodon.admin_domain_blocks
182.. automethod:: Mastodon.admin_create_domain_block
183.. automethod:: Mastodon.admin_update_domain_block
184.. automethod:: Mastodon.admin_delete_domain_block
185.. automethod:: Mastodon.admin_measures
186.. automethod:: Mastodon.admin_dimensions
187.. automethod:: Mastodon.admin_retention
188
diff --git a/docs/index.rst b/docs/index.rst
index ed8a578..d5a7e88 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -53,9 +53,10 @@ Mastodon.py contains work by a large number of contributors, many of which have
53put significant work into making it a better library. You can find some information 53put significant work into making it a better library. You can find some information
54about who helped with which particular feature or fix in the changelog. 54about who helped with which particular feature or fix in the changelog.
55 55
56.. _Mastodon.py on GitHub: https://github.com/halcy/Mastodon.py
56.. _Mastodon: https://github.com/mastodon/mastodon 57.. _Mastodon: https://github.com/mastodon/mastodon
57.. _Mastodon flagship instance: https://mastodon.social/ 58.. _The mastodon project as such: https://joinmastodon.org/
58.. _Official Mastodon API docs: https://docs.joinmastodon.org/client/intro/ 59.. _Official Mastodon API docs: https://docs.joinmastodon.org/api/guidelines/
59 60
60.. toctree:: 61.. toctree::
61 :caption: Introduction 62 :caption: Introduction
@@ -68,4 +69,20 @@ about who helped with which particular feature or fix in the changelog.
68.. toctree:: 69.. toctree::
69 :caption: API methods 70 :caption: API methods
70 71
71 04_auth \ No newline at end of file 72 04_auth
73 05_statuses
74 06_accounts
75 07_timelines
76 08_instances
77 09_notifications
78 10_streaming
79 11_misc
80 12_utilities
81 13_admin
82
83.. toctree::
84 :caption: Appendix
85
86 14_contributing
87 15_everything
88 \ No newline at end of file
diff --git a/docs/update_everything_page.sh b/docs/update_everything_page.sh
new file mode 100755
index 0000000..89da4cc
--- /dev/null
+++ b/docs/update_everything_page.sh
@@ -0,0 +1,8 @@
1#!/bin/bash
2echo "Every function on a huge CTRL-F-able page" > 15_everything.rst
3echo "=========================================" >> 15_everything.rst
4echo ".. py:module:: mastodon" >> 15_everything.rst
5echo ".. py:class: Mastodon" >> 15_everything.rst
6echo "" >> 15_everything.rst
7cat 01_general.rst 02_return_values.rst 03_errors.rst 04_auth.rst 05_statuses.rst 06_accounts.rst 07_timelines.rst 08_instances.rst 09_notifications.rst 10_streaming.rst 11_misc.rst 12_utilities.rst 13_admin.rst | grep -E "automethod|autoclass" >> 15_everything.rst
8echo "" >> 15_everything.rst
Powered by cgit v1.2.3 (git 2.41.0)