From 47c744e5e28102c1d94371edb2ff002d10ed866c Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Wed, 3 Jul 2019 17:35:38 +0200 Subject: [PATCH] Fix reST any roles/references --- docs/conf.py | 5 +++++ docs/examples.rst | 8 ++++---- docs/faq.rst | 2 +- docs/index.rst | 6 +++--- docs/intro.rst | 26 +++++++++++++------------- docs/testing.rst | 2 +- fbchat/_attachment.py | 2 +- fbchat/_client.py | 24 ++++++++++++------------ fbchat/_thread.py | 4 ++-- 9 files changed, 42 insertions(+), 37 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 98c908a..6307ba6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,6 +54,11 @@ master_doc = "index" # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +# The reST default role (used for this markup: `text`) to use for all +# documents. +# +default_role = "any" + # If true, '()' will be appended to :func: etc. cross-reference text. # add_function_parentheses = False diff --git a/docs/examples.rst b/docs/examples.rst index 9b4e682..44204ee 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -4,13 +4,13 @@ Examples ======== -These are a few examples on how to use `fbchat`. Remember to swap out `` and `` for your email and password +These are a few examples on how to use ``fbchat``. Remember to swap out ```` and ```` for your email and password Basic example ------------- -This will show basic usage of `fbchat` +This will show basic usage of ``fbchat`` .. literalinclude:: ../examples/basic_usage.py @@ -18,7 +18,7 @@ This will show basic usage of `fbchat` Interacting with Threads ------------------------ -This will interact with the thread in every way `fbchat` supports +This will interact with the thread in every way ``fbchat`` supports .. literalinclude:: ../examples/interract.py @@ -42,7 +42,7 @@ This will reply to any message with the same message Remove Bot ---------- -This will remove a user from a group if they write the message `Remove me!` +This will remove a user from a group if they write the message ``Remove me!`` .. literalinclude:: ../examples/removebot.py diff --git a/docs/faq.rst b/docs/faq.rst index c1c1602..a5cc660 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -23,7 +23,7 @@ Where you replace ```` with the version you want to use Will you be supporting creating posts/events/pages and so on? ------------------------------------------------------------- -We won't be focusing on anything else than chat-related things. This API is called `fbCHAT`, after all ;) +We won't be focusing on anything else than chat-related things. This API is called ``fbCHAT``, after all ;) Submitting Issues diff --git a/docs/index.rst b/docs/index.rst index 653bc05..671cd69 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,9 +30,9 @@ This project was inspired by `facebook-chat-api `_ for chat bots, so if you're familiar with node.js, this might be what you're looking for. -If you're already familiar with the basics of how Facebook works internally, go to :ref:`examples` to see example usage of `fbchat` +If you're already familiar with the basics of how Facebook works internally, go to :ref:`examples` to see example usage of ``fbchat`` Overview diff --git a/docs/intro.rst b/docs/intro.rst index c1a501d..0ac22dd 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -5,7 +5,7 @@ Introduction ============ -`fbchat` uses your email and password to communicate with the Facebook server. +``fbchat`` uses your email and password to communicate with the Facebook server. That means that you should always store your password in a separate file, in case e.g. someone looks over your shoulder while you're writing code. You should also make sure that the file's access control is appropriately restrictive @@ -28,7 +28,7 @@ Replace ```` and ```` with your email and password respectively For ease of use then most of the code snippets in this document will assume you've already completed the login process Though the second line, ``from fbchat.models import *``, is not strictly neccesary here, later code snippets will assume you've done this -If you want to change how verbose `fbchat` is, change the logging level (in :class:`Client`) +If you want to change how verbose ``fbchat`` is, change the logging level (in :class:`Client`) Throughout your code, if you want to check whether you are still logged in, use :func:`Client.isLoggedIn`. An example would be to login again if you've been logged out, using :func:`Client.login`:: @@ -50,7 +50,7 @@ A thread can refer to two things: A Messenger group chat or a single Facebook us :class:`models.ThreadType` is an enumerator with two values: ``USER`` and ``GROUP``. These will specify whether the thread is a single user chat or a group chat. -This is required for many of `fbchat`'s functions, since Facebook differentiates between these two internally +This is required for many of ``fbchat``'s functions, since Facebook differentiates between these two internally Searching for group chats and finding their ID can be done via. :func:`Client.searchForGroups`, and searching for users is possible via. :func:`Client.searchForUsers`. See :ref:`intro_fetching` @@ -87,7 +87,7 @@ Message IDs Every message you send on Facebook has a unique ID, and every action you do in a thread, like changing a nickname or adding a person, has a unique ID too. -Some of `fbchat`'s functions require these ID's, like :func:`Client.reactToMessage`, +Some of ``fbchat``'s functions require these ID's, like :func:`Client.reactToMessage`, and some of then provide this ID, like :func:`Client.sendMessage`. This snippet shows how to send a message, and then use the returned ID to react to that message with a 😍 emoji:: @@ -100,17 +100,17 @@ This snippet shows how to send a message, and then use the returned ID to react Interacting with Threads ------------------------ -`fbchat` provides multiple functions for interacting with threads +``fbchat`` provides multiple functions for interacting with threads Most functionality works on all threads, though some things, like adding users to and removing users from a group chat, logically only works on group chats -The simplest way of using `fbchat` is to send a message. -The following snippet will, as you've probably already figured out, send the message `test message` to your account:: +The simplest way of using ``fbchat`` is to send a message. +The following snippet will, as you've probably already figured out, send the message ``test message`` to your account:: message_id = client.send(Message(text='test message'), thread_id=client.uid, thread_type=ThreadType.USER) -You can see a full example showing all the possible thread interactions with `fbchat` by going to :ref:`examples` +You can see a full example showing all the possible thread interactions with ``fbchat`` by going to :ref:`examples` .. _intro_fetching: @@ -118,7 +118,7 @@ You can see a full example showing all the possible thread interactions with `fb Fetching Information -------------------- -You can use `fbchat` to fetch basic information like user names, profile pictures, thread names and user IDs +You can use ``fbchat`` to fetch basic information like user names, profile pictures, thread names and user IDs You can retrieve a user's ID with :func:`Client.searchForUsers`. The following snippet will search for users by their name, take the first (and most likely) user, and then get their user ID from the result:: @@ -132,7 +132,7 @@ The following snippet will search for users by their name, take the first (and m Since this uses Facebook's search functions, you don't have to specify the whole name, first names will usually be enough -You can see a full example showing all the possible ways to fetch information with `fbchat` by going to :ref:`examples` +You can see a full example showing all the possible ways to fetch information with ``fbchat`` by going to :ref:`examples` .. _intro_sessions: @@ -140,7 +140,7 @@ You can see a full example showing all the possible ways to fetch information wi Sessions -------- -`fbchat` provides functions to retrieve and set the session cookies. +``fbchat`` provides functions to retrieve and set the session cookies. This will enable you to store the session cookies in a separate file, so that you don't have to login each time you start your script. Use :func:`Client.getSession` to retrieve the cookies:: @@ -164,13 +164,13 @@ Or you can set the ``session_cookies`` on your initial login. Listening & Events ------------------ -To use the listening functions `fbchat` offers (like :func:`Client.listen`), +To use the listening functions ``fbchat`` offers (like :func:`Client.listen`), you have to define what should be executed when certain events happen. By default, (most) events will just be a `logging.info` statement, meaning it will simply print information to the console when an event happens .. note:: - You can identify the event methods by their `on` prefix, e.g. `onMessage` + You can identify the event methods by their ``on`` prefix, e.g. `onMessage` The event actions can be changed by subclassing the :class:`Client`, and then overwriting the event methods:: diff --git a/docs/testing.rst b/docs/testing.rst index 7b73608..9dbb9b7 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -15,7 +15,7 @@ To use the tests, copy ``tests/data.json`` to ``tests/my_data.json`` or type the Please remember to test all supported python versions. If you've made any changes to the 2FA functionality, test it with a 2FA enabled account. -If you only want to execute specific tests, pass the function names in the command line (not including the `test_` prefix). Example:: +If you only want to execute specific tests, pass the function names in the command line (not including the ``test_`` prefix). Example:: $ python tests.py sendMessage sessions sendEmoji diff --git a/fbchat/_attachment.py b/fbchat/_attachment.py index 7270c74..640f7a6 100644 --- a/fbchat/_attachment.py +++ b/fbchat/_attachment.py @@ -36,7 +36,7 @@ class ShareAttachment(Attachment): source = attr.ib(None) #: URL of the attachment image image_url = attr.ib(None) - #: URL of the original image if Facebook uses `safe_image` + #: URL of the original image if Facebook uses ``safe_image`` original_image_url = attr.ib(None) #: Width of the image image_width = attr.ib(None) diff --git a/fbchat/_client.py b/fbchat/_client.py index 31db216..3fc2235 100644 --- a/fbchat/_client.py +++ b/fbchat/_client.py @@ -31,7 +31,7 @@ ACONTEXT = { class Client(object): """A client for the Facebook Chat (Messenger). - This is the main class of `fbchat`, which contains all the methods you use to + This is the main class of ``fbchat``, which contains all the methods you use to interact with Facebook. You can extend this class, and overwrite the ``on`` methods, to provide custom event handling (mainly useful while listening). """ @@ -53,7 +53,7 @@ class Client(object): def uid(self): """The ID of the client. - Can be used as `thread_id`. See :ref:`intro_threads` for more info. + Can be used as ``thread_id``. See :ref:`intro_threads` for more info. """ return self._uid @@ -68,12 +68,12 @@ class Client(object): ): """Initialize and log in the client. - :param email: Facebook `email`, `id` or `phone number` + :param email: Facebook ``email``, ``id`` or ``phone number`` :param password: Facebook account password :param user_agent: Custom user agent to use when sending requests. If `None`, user agent will be chosen from a premade list :param max_tries: Maximum number of times to try logging in :param session_cookies: Cookies from a previous session (Will default to login if these are invalid) - :param logging_level: Configures the `logging level `_. Defaults to `INFO` + :param logging_level: Configures the `logging level `_. Defaults to ``logging.INFO`` :type max_tries: int :type session_cookies: dict :type logging_level: int @@ -178,7 +178,7 @@ class Client(object): def graphql_request(self, query): """ - Shorthand for `graphql_requests(query)[0]` + Shorthand for ``graphql_requests(query)[0]`` :raises: FBchatException if request failed """ @@ -214,7 +214,7 @@ class Client(object): :param session_cookies: A dictionay containing session cookies :type session_cookies: dict - :return: False if `session_cookies` does not contain proper cookies + :return: False if ``session_cookies`` does not contain proper cookies :rtype: bool """ try: @@ -233,9 +233,9 @@ class Client(object): def login(self, email, password, max_tries=5, user_agent=None): """ - Uses `email` and `password` to login the user (If the user is already logged in, this will do a re-login) + Uses ``email`` and ``password`` to login the user (If the user is already logged in, this will do a re-login) - :param email: Facebook `email` or `id` or `phone number` + :param email: Facebook ``email`` or ``id`` or ``phone number`` :param password: Facebook account password :param max_tries: Maximum number of times to try logging in :type max_tries: int @@ -965,7 +965,7 @@ class Client(object): def getUserActiveStatus(self, user_id): """ Gets friend active status as an :class:`models.ActiveStatus` object. - Returns `None` if status isn't known. + Returns ``None`` if status isn't known. .. warning:: Only works when listening. @@ -2845,8 +2845,8 @@ class Client(object): This method is useful if you want to control fbchat from an external event loop .. warning:: - `markAlive` parameter is deprecated now, use :func:`fbchat.Client.setActiveStatus` - or `markAlive` parameter in :func:`fbchat.Client.listen` instead. + ``markAlive`` parameter is deprecated, use :func:`Client.setActiveStatus` + or ``markAlive`` parameter in :func:`Client.listen` instead. :return: Whether the loop should keep running :rtype: bool @@ -2970,7 +2970,7 @@ class Client(object): :param mid: The message ID :param author_id: The ID of the author - :param message: (deprecated. Use `message_object.text` instead) + :param message: (deprecated. Use ``message_object.text`` instead) :param message_object: The message (As a `Message` object) :param thread_id: Thread ID that the message was sent to. See :ref:`intro_threads` :param thread_type: Type of thread that the message was sent to. See :ref:`intro_threads` diff --git a/fbchat/_thread.py b/fbchat/_thread.py index 3206140..6e44bc1 100644 --- a/fbchat/_thread.py +++ b/fbchat/_thread.py @@ -62,9 +62,9 @@ class ThreadColor(Enum): class Thread(object): """Represents a Facebook thread""" - #: The unique identifier of the thread. Can be used a `thread_id`. See :ref:`intro_threads` for more info + #: The unique identifier of the thread. Can be used a ``thread_id``. See :ref:`intro_threads` for more info uid = attr.ib(converter=str) - #: Specifies the type of thread. Can be used a `thread_type`. See :ref:`intro_threads` for more info + #: Specifies the type of thread. Can be used a ``thread_type``. See :ref:`intro_threads` for more info type = attr.ib() #: A url to the thread's picture photo = attr.ib(None)