diff --git a/docs/Makefile b/docs/Makefile index 32a03e5e..d4bb2cbb 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,10 +1,10 @@ # Minimal makefile for Sphinx documentation # -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = topggpy +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build SOURCEDIR = . BUILDDIR = _build @@ -17,4 +17,4 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css deleted file mode 100644 index c7e6795e..00000000 --- a/docs/_static/css/custom.css +++ /dev/null @@ -1,7 +0,0 @@ -header #logo-container img { - height: 100px; -} - -#search input[type="text"] { - font-size: 1em; -} \ No newline at end of file diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 00000000..ad108bb2 Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_static/img/favicon-16x16.png b/docs/_static/img/favicon-16x16.png deleted file mode 100644 index 58c60e92..00000000 Binary files a/docs/_static/img/favicon-16x16.png and /dev/null differ diff --git a/docs/_static/script.js b/docs/_static/script.js new file mode 100644 index 00000000..acb46774 --- /dev/null +++ b/docs/_static/script.js @@ -0,0 +1,40 @@ +document.addEventListener('load', () => { + try { + document.querySelector('.edit-this-page').remove() + + // remove these useless crap that appears on official readthedocs builds + document.querySelector('#furo-readthedocs-versions').remove() + document.querySelector('.injected').remove() + } catch { + // we're building this locally, forget it + } +}) + +const tocDrawer = document.querySelector('aside.toc-drawer') + +if (document.querySelector('section#topggpy')) { + // we don't need the right sidebar on the main landing page + tocDrawer.remove() +} else { + tocDrawer.style.visibility = 'visible' +} + +// remove related pages in the footer +document.querySelector('.related-pages').remove() + +// remove all header links +for (const headerLink of document.querySelectorAll('.headerlink')) { + headerLink.remove() +} + +for (const page of document.querySelectorAll('.sidebar-scroll li')) { + const link = page.querySelector('a') + const label = page.querySelector('label') + + if (label) { + link.addEventListener('click', event => { + event.preventDefault() + label.click() + }) + } +} \ No newline at end of file diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 00000000..be822495 --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,65 @@ +body { + --color-link-underline: rgba(0, 0, 0, 0%); + --color-link-underline--hover: var(--color-link); + --color-inline-code-background: rgba(0, 0, 0, 0%); + --color-api-background-hover: var(--color-background-primary); + --color-highlight-on-target: var(--color-background-primary) !important; + --font-stack: "Manrope", sans-serif !important; + --font-stack--monospace: "Roboto Mono", monospace !important; +} + +aside.toc-drawer { + visibility: hidden; +} + +#furo-readthedocs-versions, .injected, .edit-this-page, .related-pages, .headerlink { + visibility: hidden; + user-select: none; +} + +dd dt { + color: var(--color-foreground-secondary); +} + +aside.toc-drawer .docutils:hover, .sidebar-brand-text:hover { + transition: 0.15s; + filter: opacity(75%); +} + +.highlight *, em { + font-style: normal !important; + text-decoration: none !important; + font-weight: normal !important; +} + +.sig-paren, span.p, :not(.sig-name) > span.pre { + font-weight: normal !important; +} + +:not(h1) > a.reference { + text-decoration: underline; +} + +:not(h1) > a.reference:hover { + text-decoration: none; +} + +.field-even p strong, .field-odd p strong { + font-family: var(--font-stack--monospace); +} + +h1 > a.reference:hover { + text-decoration: underline; +} + +h1 { + font-weight: 900; +} + +.sidebar-brand-text { + font-weight: bolder; +} + +.sidebar-scroll .reference.internal { + color: var(--color-brand-primary); +} \ No newline at end of file diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 69691659..00000000 --- a/docs/api.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. currentmodule:: topgg - -############# -API Reference -############# - -The following section outlines the API of topggpy. - -Index: - - .. toctree:: - :maxdepth: 2 - - api/autopost - api/client - api/data - api/errors - api/types - api/webhook \ No newline at end of file diff --git a/docs/api/autopost.rst b/docs/api/autopost.rst deleted file mode 100644 index 668af79a..00000000 --- a/docs/api/autopost.rst +++ /dev/null @@ -1,7 +0,0 @@ -####################### -Auto-post API Reference -####################### - -.. automodule:: topgg.autopost - :members: - :inherited-members: diff --git a/docs/api/client.rst b/docs/api/client.rst index 1bac1971..97a5f24a 100644 --- a/docs/api/client.rst +++ b/docs/api/client.rst @@ -1,7 +1,14 @@ -#################### -Client API Reference -#################### +Client reference +================ -.. automodule:: topgg.client - :members: - :inherited-members: \ No newline at end of file +.. autoclass:: topgg.client.Client + :members: + +.. autoclass:: topgg.errors.Error() + :members: + +.. autoclass:: topgg.errors.RequestError() + :members: + +.. autoclass:: topgg.errors.Ratelimited() + :members: \ No newline at end of file diff --git a/docs/api/data.rst b/docs/api/data.rst deleted file mode 100644 index 3f10ff2e..00000000 --- a/docs/api/data.rst +++ /dev/null @@ -1,7 +0,0 @@ -################## -Data API Reference -################## - -.. automodule:: topgg.data - :members: - :inherited-members: \ No newline at end of file diff --git a/docs/api/errors.rst b/docs/api/errors.rst deleted file mode 100644 index 804fdfa3..00000000 --- a/docs/api/errors.rst +++ /dev/null @@ -1,7 +0,0 @@ -#################### -Errors API Reference -#################### - -.. automodule:: topgg.errors - :members: - :inherited-members: \ No newline at end of file diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 00000000..066418a8 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,10 @@ +API reference +============= + +.. toctree:: + :maxdepth: 2 + + client + project + user + widget \ No newline at end of file diff --git a/docs/api/project.rst b/docs/api/project.rst new file mode 100644 index 00000000..d94bbd4c --- /dev/null +++ b/docs/api/project.rst @@ -0,0 +1,16 @@ +Project reference +================= + +.. autoclass:: topgg.project.Project() + :members: + +.. autoclass:: topgg.project.PartialProject() + :members: + +.. autoclass:: topgg.project.ProjectType() + :members: + :undoc-members: + +.. autoclass:: topgg.project.Platform() + :members: + :undoc-members: \ No newline at end of file diff --git a/docs/api/types.rst b/docs/api/types.rst deleted file mode 100644 index a6a70f84..00000000 --- a/docs/api/types.rst +++ /dev/null @@ -1,42 +0,0 @@ -#################### -Models API Reference -#################### - -.. automodule:: topgg.types - :members: - -.. autoclass:: topgg.types.DataDict - :members: - :inherited-members: - -.. autoclass:: topgg.types.BotData - :members: - :show-inheritance: - -.. autoclass:: topgg.types.BotStatsData - :members: - :show-inheritance: - -.. autoclass:: topgg.types.BriefUserData - :members: - :show-inheritance: - -.. autoclass:: topgg.types.UserData - :members: - :show-inheritance: - -.. autoclass:: topgg.types.SocialData - :members: - :show-inheritance: - -.. autoclass:: topgg.types.VoteDataDict - :members: - :show-inheritance: - -.. autoclass:: topgg.types.BotVoteData - :members: - :show-inheritance: - -.. autoclass:: topgg.types.GuildVoteData - :members: - :show-inheritance: \ No newline at end of file diff --git a/docs/api/user.rst b/docs/api/user.rst new file mode 100644 index 00000000..377cfd2c --- /dev/null +++ b/docs/api/user.rst @@ -0,0 +1,18 @@ +User reference +============== + +.. autoclass:: topgg.user.User() + :members: + +.. autoclass:: topgg.user.UserSource() + :members: + :undoc-members: + +.. autoclass:: topgg.user.Vote() + :members: + +.. autoclass:: topgg.user.PartialVote() + :members: + +.. autoclass:: topgg.user.PaginatedVotes() + :members: \ No newline at end of file diff --git a/docs/api/webhook.rst b/docs/api/webhook.rst deleted file mode 100644 index 53a41c92..00000000 --- a/docs/api/webhook.rst +++ /dev/null @@ -1,7 +0,0 @@ -##################### -Webhook API Reference -##################### - -.. automodule:: topgg.webhook - :members: - :inherited-members: \ No newline at end of file diff --git a/docs/api/widget.rst b/docs/api/widget.rst new file mode 100644 index 00000000..ea95568e --- /dev/null +++ b/docs/api/widget.rst @@ -0,0 +1,5 @@ +Widget reference +================ + +.. autoclass:: topgg.widget.Widget() + :members: \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 2d368576..d4b625be 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,233 +1,56 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -# -# topggpy documentation build configuration file, created by -# sphinx-quickstart on Thu Feb 8 18:32:44 2018. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# - -import os +from typing import TYPE_CHECKING import sys +import os +import re -import alabaster -sys.path.insert(0, os.path.abspath("../")) -from topgg import __version__ as version +sys.path.insert(0, os.path.join(os.getcwd(), '..', 'topgg')) +sys.path.insert(0, os.path.abspath('..')) -# import re +if TYPE_CHECKING: + from ..topgg.version import VERSION +else: + from version import VERSION -# -- General configuration ------------------------------------------------ +project = 'topggpy' +author = 'null8626 & Top.gg' +copyright = '' -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' +with open('../LICENSE', 'r') as f: + copyright_match = re.search(rf'[\d\-]+(?:-[\d\-]+)? {author}', f.read()) + assert copyright_match is not None -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.viewcode", - "sphinx.ext.autosectionlabel", - "sphinx.ext.extlinks", - "sphinx.ext.intersphinx", - "sphinx.ext.napoleon", -] + copyright = copyright_match.group() -autodoc_member_order = "groupwise" +version = VERSION +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx_reredirects'] -extlinks = { - "issue": ("https://github.com/top-gg/python-sdk/issues/%s", "GH-"), +autodoc_type_aliases = { + 'Listener': '~topgg.webhooks.Listener', + 'IntegrationCreateListener': '~topgg.webhooks.IntegrationCreateListener', + 'IntegrationDeleteListener': '~topgg.webhooks.IntegrationDeleteListener', + 'TestListener': '~topgg.webhooks.TestListener', + 'VoteCreateListener': '~topgg.webhooks.VoteCreateListener', } 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), + 'py': ('https://docs.python.org/3', None), + 'aio': ('https://docs.aiohttp.org/en/stable/', None), } -releases_github_path = "top-gg/python-sdk" - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" - -# The master toctree document. -master_doc = "index" - -# General information about the project. -project = "topggpy" -copyright = "2021, Assanali Mukhanov" -author = "Assanali Mukhanov" - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. - -# with open('../dbl/__init__.py') as f: -# version = re.search(r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]', f.read(), re.MULTILINE).group(1) -# The full version, including alpha/beta/rc tags. -release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ["_build"] - -# -- Options for HTML output ---------------------------------------------- - -html_theme_options = {"navigation_depth": 2} -html_theme_path = [alabaster.get_path()] -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "insegel" - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = "topgg.svg" - -# 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 "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -# html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# html_additional_pages = {} - -# If false, no module index is generated. -# html_domain_indices = True - -# If false, no index is generated. -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -html_show_sphinx = False - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' -# html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -# html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -# html_search_scorer = 'scorer.js' - - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = "topggpydoc" - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', +redirects = { + 'support-server': 'https://discord.gg/EYHTgJX', + 'repository': 'https://github.com/top-gg-community/python-sdk', + 'raw-api-reference': 'https://docs.top.gg/docs/', } -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, "topggpy.tex", "topggpy Documentation", "Assanali Mukhanov", "manual"), -] - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [(master_doc, "topggpy", "topggpy Documentation", [author], 1)] - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - master_doc, - "topggpy", - "topggpy Documentation", - author, - "topggpy", - "One line description of project.", - "Miscellaneous", - ), +html_css_files = [ + 'style.css', + 'https://fonts.googleapis.com/css2?family=Manrope:wght@200..800&display=swap', ] +html_js_files = ['script.js'] +html_static_path = ['_static'] +html_theme = 'furo' +html_title = project +html_favicon = '_static/favicon.ico' diff --git a/docs/index.rst b/docs/index.rst index a634d380..3d90e37f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,19 +3,183 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -################################### -Welcome to topggpy's documentation! -################################### +================= +Top.gg Python SDK +================= -.. toctree:: - :maxdepth: 1 + For more information, see the documentation here: https://topggpy.rtfd.io. + +The community-maintained Python library for Top.gg. + +Chapters +-------- + +- `Installation <#installation>`__ +- `Setting up <#setting-up>`__ +- `Usage <#usage>`__ + + - `Getting your project's information <#getting-your-projects-information>`__ + - `Getting your project's vote information of a user <#getting-your-projects-vote-information-of-a-user>`__ + - `Getting a cursor-based paginated list of votes for your project <#getting-a-cursor-based-paginated-list-of-votes-for-your-project>`__ + - `Posting your bot's application commands list <#posting-your-bots-application-commands-list>`__ + - `Generating widget URLs <#generating-widget-urls>`__ + - `Webhooks <#webhooks>`__ + +Installation +------------ + +.. code-block:: console + + $ pip install topggpy + +Setting up +---------- + +.. code-block:: python + + import topgg + + import os + + + token = os.getenv('TOPGG_TOKEN') + assert token is not None, 'Missing TOPGG_TOKEN environment variable.' + + client = topgg.Client(token) + +Usage +----- + +Getting your project's information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + project = await client.get_self() + +Getting your project's vote information of a user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Discord ID +^^^^^^^^^^ + +.. code-block:: python + + vote = await client.get_vote(topgg.UserSource.DISCORD, 661200758510977084) + +Top.gg ID +^^^^^^^^^ + +.. code-block:: python + + vote = await client.get_vote(topgg.UserSource.TOPGG, 8226924471638491136) + +Getting a cursor-based paginated list of votes for your project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from datetime import datetime + + + first_page = await client.get_votes(datetime(2026, 1, 1)) + + for vote in first_page: + print(vote) - api - whats_new + second_page = await first_page.next() -Indices and tables -================== + for vote in second_page: + print(vote) + + third_page = await second_page.next() + +Posting your bot's application commands list +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + # Array of application commands that + # can be serialized to Discord API's raw JSON format. + + await client.post_commands( + [ + { + 'id': '1', + 'type': 1, + 'application_id': '1', + 'name': 'test', + 'description': 'command description', + 'default_member_permissions': '', + 'version': '1', + } + ] + ) + +Generating widget URLs +~~~~~~~~~~~~~~~~~~~~~~ + +Large +^^^^^ + +.. code-block:: python + + widget_url = topgg.Widget.large(topgg.ProjectType.DISCORD_BOT, 1026525568344264724) + +Votes +^^^^^ + +.. code-block:: python + + widget_url = topgg.Widget.votes(topgg.ProjectType.DISCORD_BOT, 1026525568344264724) + +Owner +^^^^^ + +.. code-block:: python + + widget_url = topgg.Widget.owner(topgg.ProjectType.DISCORD_BOT, 1026525568344264724) + +Social +^^^^^^ + +.. code-block:: python + + widget_url = topgg.Widget.social(topgg.ProjectType.DISCORD_BOT, 1026525568344264724) + +Webhooks +~~~~~~~~ + +With express: + +.. code-block:: python + + import topgg + + from aiohttp import web + import os + + + secret = os.getenv('TOPGG_WEBHOOK_SECRET') + assert secret is not None, 'Missing TOPGG_WEBHOOK_SECRET environment variable.' + + # POST /webhook + webhooks = topgg.Webhooks('/webhook', secret) + + @webhooks.on(topgg.PayloadType.TEST) + async def test_listener(payload: topgg.TestPayload, trace: str) -> web.Response: + print(payload) + + return web.Response(status=204) + + await webhooks.start() + +.. toctree:: + :maxdepth: 2 + :hidden: -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + api/index.rst + webhooks + support-server + repository + raw-api-reference \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat index 4fbe60d3..954237b9 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -1,36 +1,35 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build -set SPHINXPROJ=topggpy - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/raw-api-reference.rst b/docs/raw-api-reference.rst new file mode 100644 index 00000000..31105eee --- /dev/null +++ b/docs/raw-api-reference.rst @@ -0,0 +1,5 @@ +================= +Raw API reference +================= + +You should be redirected in a few moments. Otherwise, click here: https://docs.top.gg/docs/ \ No newline at end of file diff --git a/docs/repository.rst b/docs/repository.rst new file mode 100644 index 00000000..a542ad6a --- /dev/null +++ b/docs/repository.rst @@ -0,0 +1,5 @@ +================= +GitHub repository +================= + +You should be redirected in a few moments. Otherwise, click here: https://github.com/top-gg-community/python-sdk \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt index 50e29c39..63a65e99 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,4 @@ -sphinx>=8.2.3 -insegel>=1.3.1 +aiohttp +furo +pyyaml +sphinx-reredirects \ No newline at end of file diff --git a/docs/support-server.rst b/docs/support-server.rst new file mode 100644 index 00000000..35b6aa47 --- /dev/null +++ b/docs/support-server.rst @@ -0,0 +1,5 @@ +============== +Support server +============== + +You should be redirected in a few moments. Otherwise, click here: https://discord.gg/EYHTgJX \ No newline at end of file diff --git a/docs/topgg.svg b/docs/topgg.svg deleted file mode 100644 index 9afe2351..00000000 --- a/docs/topgg.svg +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - diff --git a/docs/webhooks.rst b/docs/webhooks.rst new file mode 100644 index 00000000..e12dabba --- /dev/null +++ b/docs/webhooks.rst @@ -0,0 +1,30 @@ +Webhooks reference +================== + +.. autoclass:: topgg.webhooks.Webhooks + :members: + +.. autoclass:: topgg.payload.Payload() + :members: + +.. autoclass:: topgg.payload.PayloadType() + :members: + :undoc-members: + +.. autoclass:: topgg.payload.IntegrationCreatePayload() + :members: + +.. autoclass:: topgg.payload.IntegrationDeletePayload() + :members: + +.. autoclass:: topgg.payload.TestPayload() + :members: + +.. autoclass:: topgg.payload.VoteCreatePayload() + :members: + +.. autodata:: topgg.webhooks.Listener +.. autodata:: topgg.webhooks.IntegrationCreateListener +.. autodata:: topgg.webhooks.IntegrationDeleteListener +.. autodata:: topgg.webhooks.TestListener +.. autodata:: topgg.webhooks.VoteCreateListener \ No newline at end of file diff --git a/docs/whats_new.rst b/docs/whats_new.rst deleted file mode 100644 index 8fc1d0e9..00000000 --- a/docs/whats_new.rst +++ /dev/null @@ -1,168 +0,0 @@ -.. currentmodule:: topgg - -.. _whats_new: - -########## -What's New -########## - -This page keeps a detailed human friendly rendering of what's new and changed in specific versions. - -v2.0.0a -======= -* :obj:`~.DBLClient` now doesn't take in ``discord.Client`` instance -* Introduced new `autopost `__ and `data injection `__ API -* `Webhook `__ API breaking changes -* No longer depends on any Discord API wrapper -* :obj:`~.GuildVoteData` alias - -v1.4.0 -====== - -* The type of data passed to ``on_dbl_vote`` has been changed from :class:`dict` to :obj:`BotVoteData` -* The type of data passed to ``on_dsl_vote`` has been changed from :class:`dict` to :obj:`ServerVoteData` - -v1.3.0 -====== - -* Introduced `global ratelimiter `__ to follow Top.gg global ratelimits - - * Fixed an :exc:`AttributeError` raised by :meth:`HTTPClient.request` - - * `Resource-specific ratelimit `__ is now actually resource-specific - -v1.2.0 -====== - -* Introduced global ratelimiter along with bot endpoints ratelimiter -* Follow consistency with typing in :class:`HTTPClient` and :class:`DBLClient` along with updated docstrings (:issue:`55`) - -v1.1.0 -====== - -* Introduced `data models `__ - - * :meth:`DBLClient.get_bot_votes` now returns a list of :class:`BriefUserData` objects - - * :meth:`DBLClient.get_bot_info` now returns a :class:`BotData` object - - * :meth:`DBLClient.get_guild_count` now returns a :class:`BotStatsData` object - - * :meth:`DBLClient.get_user_info` now returns a :class:`UserData` object - -* :meth:`WebhookManager.run` now returns an :class:`asyncio.Task`, meaning it can now be optionally awaited - -v1.0.1 -====== - -* :attr:`WebhookManager.webserver` now instead returns :class:`aiohttp.web.Application` for ease of use - -v1.0.0 -====== - -* Renamed the module folder from ``dbl`` to ``topgg`` -* Added ``post_shard_count`` argument to :meth:`DBLClient.post_guild_count` -* Autopost now supports automatic shard posting (:issue:`42`) -* Large webhook system rework, read the :obj:`api/webhook` section for more - - * Added support for server webhooks - -* Renamed ``DBLException`` to :class:`TopGGException` -* Renamed ``DBLClient.get_bot_upvotes()`` to :meth:`DBLClient.get_bot_votes` -* Added :meth:`DBLClient.generate_widget` along with the ``widgets`` section in the documentation -* Implemented a properly working ratelimiter -* Added :func:`on_autopost_error` -* All autopost events now follow ``on_autopost_x`` naming format, e.g. :func:`on_autopost_error`, :func:`on_autopost_success` -* Added handlers for autopost args set when autopost is disabled - -v0.4.0 -====== - -* :meth:`DBLClient.post_guild_count` now supports a custom ``guild_count`` argument, which accepts either an integer or list of integers -* Reworked how shard info is posted -* Removed ``InvalidArgument`` and ``ConnectionClosed`` exceptions -* Added ``ServerError`` exception - -v0.3.3 -====== - -* Internal changes regarding support of Top.gg migration -* Fixed errors raised when using :meth:`DBLClient.close` without built-in webhook - -v0.3.2 -====== - -* ``Client`` class has been renamed to ``DBLClient`` - -v0.3.1 -====== - -* Added ``on_guild_post``, an event that is called when autoposter successfully posts guild count -* Renamed ``get_upvote_info`` to ``get_bot_upvotes`` -* Added ``get_user_vote`` - -v0.3.0 -====== - -* :class:`DBLClient` now has ``autopost`` kwarg that will post server count automatically every 30 minutes -* Fixed code 403 errors -* Added ``on_dbl_vote``, an event that is called when you test your webhook -* Added ``on_dbl_test``, an event that is called when someone tests your webhook - -v0.2.1 -====== - -* Added webhook -* Removed support for discord.py versions lower than 1.0.0 -* Made :meth:`DBLClient.get_weekend_status` return a boolean value -* Added webhook example in README -* Removed ``post_server_count`` and ``get_server_count`` - -v0.2.0 -====== - -* Added ``post_guild_count`` - - * Made ``post_server_count`` an alias for ``post_guild_count`` - - * Added ``get_guild_count`` - -* Made ``get_server_count`` an alias for ``get_guild_count`` - -* Added :meth:`DBLClient.get_weekend_status` -* Removed all parameters from :meth:`DBLClient.get_upvote_info` -* Added limit to :meth:`DBLClient.get_bots` -* Fixed example in README - -v0.1.6 -====== - -* Bug fixes & improvements - -v0.1.4 -====== - -* Initial ratelimit handling - -v0.1.3 -====== - -* Added documentation -* Fixed some minor bugs - -v0.1.2 -====== - -Initial release - -* Working - - * POSTing server count - * GET bot info, server count, upvote count, upvote info - * GET all bots - * GET specific user info - * GET widgets (large and small) including custom ones. See `Top.gg docs `_ for more info. - -* Not Working / Implemented - - * Searching for bots via the api