From 745e0e512328cba69e1fbc802f0751ef4725fe83 Mon Sep 17 00:00:00 2001 From: grey-cat-1908 Date: Sun, 4 Jun 2023 12:21:28 +0300 Subject: [PATCH] better docs --- boticordpy/client.py | 143 +-------------------------------- boticordpy/types.py | 35 ++++++-- docs/source/api.rst | 3 +- docs/source/api/autopost.rst | 4 +- docs/source/api/client.rst | 8 +- docs/source/api/exceptions.rst | 4 +- docs/source/api/types.rst | 38 ++++++++- docs/source/api/webhook.rst | 7 -- docs/source/conf.py | 42 +++++----- docs/source/index.rst | 1 - docs/source/other.rst | 38 --------- 11 files changed, 99 insertions(+), 224 deletions(-) delete mode 100644 docs/source/api/webhook.rst delete mode 100644 docs/source/other.rst diff --git a/boticordpy/client.py b/boticordpy/client.py index 18c7236..1d8aaed 100644 --- a/boticordpy/client.py +++ b/boticordpy/client.py @@ -54,7 +54,7 @@ class BoticordClient: """Post Bot's stats. Args: - bot_id (Union[:obj:`str`, :obj:`) + bot_id (Union[:obj:`str`, :obj:`int`]) Id of the bot to post stats of. servers ( :obj:`int` ) Bot's servers count @@ -62,6 +62,7 @@ class BoticordClient: Bot's shards count users ( :obj:`int` ) Bot's users count + Returns: :obj:`~.types.ResourceBot`: ResourceBot object. @@ -71,146 +72,6 @@ class BoticordClient: ) return boticord_types.ResourceBot.from_dict(response) - async def get_server_info(self, server_id: int): - """Gets information about specified server. - - Args: - server_id (:obj:`int`) - Id of the server - - Returns: - :obj:`~.types.Server`: - Server object. - """ - response = await self.http.get_server_info(server_id) - return boticord_types.Server(**response) - - async def get_server_comments(self, server_id: int) -> list: - """Gets list of comments of specified server. - - Args: - server_id (:obj:`int`) - Id of the server - - Returns: - :obj:`list` [ :obj:`~.types.SingleComment` ]: - List of comments. - """ - response = await self.http.get_server_comments(server_id) - return [boticord_types.SingleComment(**comment) for comment in response] - - async def post_server_stats(self, payload: dict) -> dict: - """Post Server's stats. You must be Boticord-Service bot. - Payload is raw, because if you use it - you know what you are doing. - You can find more information about payload `in BotiCord API Docs `_ - - Args: - payload (:obj:`dict`) - Custom data (Use Boticord API docs.) - Returns: - :obj:`dict`: - Boticord API Response. - """ - response = await self.http.post_server_stats(payload) - return response - - async def get_user_info(self, user_id: int): - """Gets information about specified user. - - Args: - user_id (:obj:`int`) - Id of the user - - Returns: - :obj:`~.types.UserProfile`: - User Profile object. - """ - response = await self.http.get_user_info(user_id) - return boticord_types.UserProfile(**response) - - async def get_user_comments(self, user_id: int): - """Gets comments of specified user. - - Args: - user_id (:obj:`int`) - Id of the user - - Returns: - :obj:`~.types.UserComments`: - User comments on Bots and Servers pages. - """ - response = await self.http.get_user_comments(user_id) - return boticord_types.UserComments(**response) - - async def get_user_bots(self, user_id: int) -> list: - """Gets list of bots of specified user. - - Args: - user_id (:obj:`int`) - Id of the user - - Returns: - :obj:`list` [ :obj:`~.types.SimpleBot` ]: - List of simple information about users bots. - """ - response = await self.http.get_user_bots(user_id) - return [boticord_types.SimpleBot(**bot) for bot in response] - - async def get_my_shorted_links(self, *, code: str = None): - """Gets shorted links of an authorized user - - Args: - code (:obj:`str`) - Code of shorted link. Could be None. - - Returns: - Union[:obj:`list` [ :obj:`~.types.ShortedLink` ], :obj:`~types.ShortedLink`]: - List of shorted links if none else shorted link - """ - response = await self.http.get_my_shorted_links(code) - - return ( - [boticord_types.ShortedLink(**link) for link in response] - if code is None - else boticord_types.ShortedLink(**response[0]) - ) - - async def create_shorted_link(self, *, code: str, link: str, domain=1): - """Creates new shorted link - - Args: - code (:obj:`str`) - Code of link to short. - link (:obj:`str`) - Link to short. - domain (:obj:`~.types.LinkDomain`) - Domain to use in shorted link - - Returns: - :obj:`~types.ShortedLink`: - Shorted Link - """ - response = await self.http.create_shorted_link(code, link, domain=domain) - - return boticord_types.ShortedLink(**response) - - async def delete_shorted_link(self, code: str, domain=1): - """Deletes shorted link - - Args: - code (:obj:`str`) - Code of link to delete. - domain (:obj:`~.types.LinkDomain`) - Domain that is used in shorted link - - Returns: - :obj:`bool`: - Is link deleted successfully? - """ - response = await self.http.delete_shorted_link(code, domain) - - return response.get("ok", False) - def autopost(self) -> AutoPost: """Returns a helper instance for auto-posting. diff --git a/boticordpy/types.py b/boticordpy/types.py index 7bd826a..c3d2bf7 100644 --- a/boticordpy/types.py +++ b/boticordpy/types.py @@ -212,33 +212,56 @@ class BotLibrary(IntEnum): """The library that the bot is based on""" DISCORD4J = 1 + """Discord4j""" + DISCORDCR = 2 + """Discordcr""" + DISCORDGO = 3 + """DiscordGO""" + DISCORDDOO = 4 + """Discordoo""" + DSHARPPLUS = 5 + """DSharpPlus""" + DISCORDJS = 6 + """Discord.js""" + DISCORDNET = 7 + """Discord.Net""" + DISCORDPY = 8 + """discord.py""" + ERIS = 9 + """eris""" + JAVACORD = 10 + """JavaCord""" + JDA = 11 + """JDA""" + OTHER = 12 + """Other""" class ResourceStatus(IntEnum): - """Bot status on monitoring""" + """Status of the project on monitoring""" HIDDEN = 0 - """Bot is hidden""" + """is hidden""" PUBLIC = 1 - """Bot is public""" + """is public""" BANNED = 2 - """Bot is banned""" + """is banned""" PENDING = 3 - """Bor is pending""" + """is pending""" class BotTag(IntEnum): @@ -316,7 +339,7 @@ class UserLinks(APIObjectBase): The dictionary to convert into a UserLinks. """ - self: ResourceUp = super().__new__(cls) + self: UserLinks = super().__new__(cls) self.vk = data.get("vk") self.telegram = data.get("telegram") diff --git a/docs/source/api.rst b/docs/source/api.rst index 706644a..6540202 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -14,5 +14,4 @@ API Reference for the boticordpy Module api/client api/autopost api/exceptions - api/types - api/webhook \ No newline at end of file + api/types \ No newline at end of file diff --git a/docs/source/api/autopost.rst b/docs/source/api/autopost.rst index 82e9f81..30ae03b 100644 --- a/docs/source/api/autopost.rst +++ b/docs/source/api/autopost.rst @@ -1,6 +1,6 @@ -#################### +########################### AutoPost API Reference -#################### +########################### .. automodule:: boticordpy.autopost :members: diff --git a/docs/source/api/client.rst b/docs/source/api/client.rst index cb589f2..6ea5f18 100644 --- a/docs/source/api/client.rst +++ b/docs/source/api/client.rst @@ -1,7 +1,11 @@ +.. currentmodule:: boticordpy + #################### Client API Reference #################### -.. automodule:: boticordpy.client - :members: +BoticordClient +----------------- + +.. autoclass:: BoticordClient :inherited-members: diff --git a/docs/source/api/exceptions.rst b/docs/source/api/exceptions.rst index 5fbedef..92ffe2c 100644 --- a/docs/source/api/exceptions.rst +++ b/docs/source/api/exceptions.rst @@ -1,6 +1,6 @@ -#################### +########################## Exceptions API Reference -#################### +########################## .. automodule:: boticordpy.exceptions :members: diff --git a/docs/source/api/types.rst b/docs/source/api/types.rst index dc0a263..3f4771d 100644 --- a/docs/source/api/types.rst +++ b/docs/source/api/types.rst @@ -1,8 +1,40 @@ +.. currentmodule:: boticordpy.types + #################### Models API Reference #################### -We recommend you to read the `boticordpy/types.py `_ file, because it is much easier to read than here. - -.. automodule:: boticordpy.types +.. autoclass:: ResourceRating + :members: + +.. autoclass:: ResourceUp + :members: + +Enums +------- + +.. autoclass:: BotLibrary + :members: + +.. autoclass:: BotTag + :members: + +.. autoclass:: ResourceStatus + :members: + + +Bots +------ + +.. autoclass:: ResourceBot + :members: + + +Users +------ + +.. autoclass:: UserLinks + :members: + +.. autoclass:: PartialUser :members: diff --git a/docs/source/api/webhook.rst b/docs/source/api/webhook.rst deleted file mode 100644 index 59198b0..0000000 --- a/docs/source/api/webhook.rst +++ /dev/null @@ -1,7 +0,0 @@ -#################### -Webhook API Reference -#################### - -.. automodule:: boticordpy.webhook - :members: - :inherited-members: diff --git a/docs/source/conf.py b/docs/source/conf.py index a79baa0..961f62b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,11 +23,11 @@ import os sys.path.insert(0, os.path.abspath("../..")) project = "BoticordPY" -copyright = "2022, Victor Kotlin (Marakarka)" -author = "Victor Kotlin (Marakarka)" +copyright = "2022 - 2023, Viktor K (Marakarka)" +author = "Viktor K (Marakarka)" # The full version, including alpha/beta/rc tags -release = "2.2.2" +release = "3.0.0a" # -- General configuration --------------------------------------------------- @@ -36,41 +36,43 @@ release = "2.2.2" # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "sphinx_design", "sphinx.ext.napoleon", "sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.autosectionlabel", "sphinx.ext.extlinks", + "sphinxcontrib_trio" ] +autodoc_default_options = {"members": True, "show-inheritance": True, 'member-order': 'bysource'} + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. +add_module_names = False + exclude_patterns = [] intersphinx_mapping = { "py": ("https://docs.python.org/3", None), - "discord": ("https://discordpy.readthedocs.io/en/latest/", None), "aiohttp": ("https://docs.aiohttp.org/en/stable/", None), } # -- Options for HTML output ------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinxawesome_theme" - -html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "custom.css" will overwrite the builtin "custom.css". +html_theme = "furo" +html_theme_options = { + "sidebar_hide_name": True, +} +pygments_style = "monokai" +default_dark_mode = True html_static_path = ["_static"] +html_css_files = ["custom.css"] - -def setup(app): - app.add_css_file("custom.css") +rst_prolog = """ +.. |coro| replace:: This function is a |coroutine_link|_. +.. |maybecoro| replace:: This function *could be a* |coroutine_link|_. +.. |coroutine_link| replace:: *coroutine* +.. _coroutine_link: https://docs.python.org/3/library/asyncio-task.html#coroutine +""" diff --git a/docs/source/index.rst b/docs/source/index.rst index 63629a7..c903f84 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,7 +11,6 @@ This is a documentation for wrapper for BotiCord API. quickstart api - other Links ===== diff --git a/docs/source/other.rst b/docs/source/other.rst deleted file mode 100644 index eb26853..0000000 --- a/docs/source/other.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. currentmodule:: boticordpy - -.. other: - -Other Information -================= - -########## -Listeners -########## - -When you work with BotiCord Webhooks you may receive a lot of events. -To make it easier to handle them there is a list of the events you can receive: - -.. csv-table:: - :header: "BotiCord Events", "Meaning" - :widths: 20, 20 - - "test_webhook_message", "Test message." - "new_bot_comment", "On new bot comment" - "edit_bot_comment", "On bot comment edit" - "delete_bot_comment", "On bot comment delete" - "new_bot_bump", "On new bot bump" - "new_server_comment", "On new server comment" - "edit_server_comment", "On server comment edit" - "delete_server_comment", "On server comment delete" - "new_server_bump", "On new server bump" - - -################## -Callback functions -################## - -.. warning:: - - Callback functions must be a **coroutine**. If they aren't, then you might get unexpected - errors. In order to turn a function into a coroutine they must be ``async def`` - functions.