From 795912bff63168801a80fb93ee339b3777ab224d Mon Sep 17 00:00:00 2001 From: jrootjunior Date: Tue, 28 Jan 2020 14:03:29 +0200 Subject: [PATCH] improve docs --- docs/_api_version.md | 1 + docs/api/index.md | 14 ++++--- docs/api/methods/index.md | 77 +++++++++++++++++++++++++++++++++++++++ docs/api/types/index.md | 69 +++++++++++++++++++++++++++++++++++ docs/index.md | 8 ++-- mkdocs.yml | 2 + poetry.lock | 16 +++++++- pyproject.toml | 1 + 8 files changed, 177 insertions(+), 11 deletions(-) create mode 100644 docs/_api_version.md create mode 100644 docs/api/methods/index.md create mode 100644 docs/api/types/index.md diff --git a/docs/_api_version.md b/docs/_api_version.md new file mode 100644 index 00000000..b3d791d7 --- /dev/null +++ b/docs/_api_version.md @@ -0,0 +1 @@ +4.6 diff --git a/docs/api/index.md b/docs/api/index.md index 68f47da0..5164d96f 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1,16 +1,17 @@ # Overview -**aiogram** now is fully support of [Telegram Bot API v4.6](https://core.telegram.org/bots/api) +**aiogram** now is fully support of [Telegram Bot API v{!_api_version.md!}](https://core.telegram.org/bots/api) All API methods and types is fully autogenerated from Telegram Bot API docs by parser with code-generator. Package: `aiogram.api` - + ## Methods All API methods is wrapped as [pydantic](https://pydantic-docs.helpmanual.io/) models and placed in `aiogram.api.methods` package so that's mean all values which you pass as arguments to the methods will be validated. Here is all methods is classes and in due to Python standards all classes named in upper camel case, for example methods `sendMessage` has the name `SendMessage` -Also in places where you can send + +Full list of methods can be found in section "[Methods](methods/index.md)" ## Types @@ -21,9 +22,11 @@ In this place makes some more differences with official documentations: - timestamps has `datetime.datetime` type instead of `int` - InputFile is used for sending files and is not use `pydantic.BaseModel` as base class +Full list of methods can be found in section "[Types](types/index.md)" + ## Bot instance -Bot instance can be created from `aiogram.Bot` (`#!python3 from aiogram import Bot`) +Bot instance can be created from `aiogram.Bot` (`#!python3 from aiogram import Bot`) and you can't use API methods without instance of bot with configured token. Constructor specification: @@ -32,4 +35,5 @@ Constructor specification: | `token` | `#!python3 str` | Telegram Bot token (Obtained from [@BotFather](https://t.me/BotFather)). | | `session` | `#!python3 Optional[BaseSession]` | HTTP Client session (For example AiohttpSession). If not specified it will be automatically created. | | `parse_mode` | `#!python3 Optional[str]` | Default parse mode. If specified it will be propagated into the API methods at runtime. | - + +This class has aliases for all API methods and named in `lower_camel_case`. For example `sendMessage` named `send_message` and has the same specification with all class-based methods. diff --git a/docs/api/methods/index.md b/docs/api/methods/index.md new file mode 100644 index 00000000..3ded69b5 --- /dev/null +++ b/docs/api/methods/index.md @@ -0,0 +1,77 @@ +# Methods + +Here is list of all available API methods: +* Getting updates + - [getUpdates](get_updates.md) + - [setWebhook](set_webhook.md) + - [deleteWebhook](delete_webhook.md) + - [getWebhookInfo](get_webhook_info.md) +* Available methods + - [getMe](get_me.md) + - [sendMessage](send_message.md) + - [forwardMessage](forward_message.md) + - [sendPhoto](send_photo.md) + - [sendAudio](send_audio.md) + - [sendDocument](send_document.md) + - [sendVideo](send_video.md) + - [sendAnimation](send_animation.md) + - [sendVoice](send_voice.md) + - [sendVideoNote](send_video_note.md) + - [sendMediaGroup](send_media_group.md) + - [sendLocation](send_location.md) + - [editMessageLiveLocation](edit_message_live_location.md) + - [stopMessageLiveLocation](stop_message_live_location.md) + - [sendVenue](send_venue.md) + - [sendContact](send_contact.md) + - [sendPoll](send_poll.md) + - [sendChatAction](send_chat_action.md) + - [getUserProfilePhotos](get_user_profile_photos.md) + - [getFile](get_file.md) + - [kickChatMember](kick_chat_member.md) + - [unbanChatMember](unban_chat_member.md) + - [restrictChatMember](restrict_chat_member.md) + - [promoteChatMember](promote_chat_member.md) + - [setChatAdministratorCustomTitle](set_chat_administrator_custom_title.md) + - [setChatPermissions](set_chat_permissions.md) + - [exportChatInviteLink](export_chat_invite_link.md) + - [setChatPhoto](set_chat_photo.md) + - [deleteChatPhoto](delete_chat_photo.md) + - [setChatTitle](set_chat_title.md) + - [setChatDescription](set_chat_description.md) + - [pinChatMessage](pin_chat_message.md) + - [unpinChatMessage](unpin_chat_message.md) + - [leaveChat](leave_chat.md) + - [getChat](get_chat.md) + - [getChatAdministrators](get_chat_administrators.md) + - [getChatMembersCount](get_chat_members_count.md) + - [getChatMember](get_chat_member.md) + - [setChatStickerSet](set_chat_sticker_set.md) + - [deleteChatStickerSet](delete_chat_sticker_set.md) + - [answerCallbackQuery](answer_callback_query.md) +* Updating messages + - [editMessageText](edit_message_text.md) + - [editMessageCaption](edit_message_caption.md) + - [editMessageMedia](edit_message_media.md) + - [editMessageReplyMarkup](edit_message_reply_markup.md) + - [stopPoll](stop_poll.md) + - [deleteMessage](delete_message.md) +* Stickers + - [sendSticker](send_sticker.md) + - [getStickerSet](get_sticker_set.md) + - [uploadStickerFile](upload_sticker_file.md) + - [createNewStickerSet](create_new_sticker_set.md) + - [addStickerToSet](add_sticker_to_set.md) + - [setStickerPositionInSet](set_sticker_position_in_set.md) + - [deleteStickerFromSet](delete_sticker_from_set.md) +* Inline mode + - [answerInlineQuery](answer_inline_query.md) +* Payments + - [sendInvoice](send_invoice.md) + - [answerShippingQuery](answer_shipping_query.md) + - [answerPreCheckoutQuery](answer_pre_checkout_query.md) +* Telegram Passport + - [setPassportDataErrors](set_passport_data_errors.md) +* Games + - [sendGame](send_game.md) + - [setGameScore](set_game_score.md) + - [getGameHighScores](get_game_high_scores.md) diff --git a/docs/api/types/index.md b/docs/api/types/index.md new file mode 100644 index 00000000..a981b10f --- /dev/null +++ b/docs/api/types/index.md @@ -0,0 +1,69 @@ +# Methods + +Here is list of all available API methods: +* Getting updates + - [Update](update.md) + - [WebhookInfo](webhook_info.md) +* Available methods +* Updating messages +* Stickers + - [Sticker](sticker.md) + - [StickerSet](sticker_set.md) + - [MaskPosition](mask_position.md) +* Inline mode + - [InlineQuery](inline_query.md) + - [InlineQueryResult](inline_query_result.md) + - [InlineQueryResultArticle](inline_query_result_article.md) + - [InlineQueryResultPhoto](inline_query_result_photo.md) + - [InlineQueryResultGif](inline_query_result_gif.md) + - [InlineQueryResultMpeg4Gif](inline_query_result_mpeg4_gif.md) + - [InlineQueryResultVideo](inline_query_result_video.md) + - [InlineQueryResultAudio](inline_query_result_audio.md) + - [InlineQueryResultVoice](inline_query_result_voice.md) + - [InlineQueryResultDocument](inline_query_result_document.md) + - [InlineQueryResultLocation](inline_query_result_location.md) + - [InlineQueryResultVenue](inline_query_result_venue.md) + - [InlineQueryResultContact](inline_query_result_contact.md) + - [InlineQueryResultGame](inline_query_result_game.md) + - [InlineQueryResultCachedPhoto](inline_query_result_cached_photo.md) + - [InlineQueryResultCachedGif](inline_query_result_cached_gif.md) + - [InlineQueryResultCachedMpeg4Gif](inline_query_result_cached_mpeg4_gif.md) + - [InlineQueryResultCachedSticker](inline_query_result_cached_sticker.md) + - [InlineQueryResultCachedDocument](inline_query_result_cached_document.md) + - [InlineQueryResultCachedVideo](inline_query_result_cached_video.md) + - [InlineQueryResultCachedVoice](inline_query_result_cached_voice.md) + - [InlineQueryResultCachedAudio](inline_query_result_cached_audio.md) + - [InputMessageContent](input_message_content.md) + - [InputTextMessageContent](input_text_message_content.md) + - [InputLocationMessageContent](input_location_message_content.md) + - [InputVenueMessageContent](input_venue_message_content.md) + - [InputContactMessageContent](input_contact_message_content.md) + - [ChosenInlineResult](chosen_inline_result.md) +* Payments + - [LabeledPrice](labeled_price.md) + - [Invoice](invoice.md) + - [ShippingAddress](shipping_address.md) + - [OrderInfo](order_info.md) + - [ShippingOption](shipping_option.md) + - [SuccessfulPayment](successful_payment.md) + - [ShippingQuery](shipping_query.md) + - [PreCheckoutQuery](pre_checkout_query.md) +* Telegram Passport + - [PassportData](passport_data.md) + - [PassportFile](passport_file.md) + - [EncryptedPassportElement](encrypted_passport_element.md) + - [EncryptedCredentials](encrypted_credentials.md) + - [PassportElementError](passport_element_error.md) + - [PassportElementErrorDataField](passport_element_error_data_field.md) + - [PassportElementErrorFrontSide](passport_element_error_front_side.md) + - [PassportElementErrorReverseSide](passport_element_error_reverse_side.md) + - [PassportElementErrorSelfie](passport_element_error_selfie.md) + - [PassportElementErrorFile](passport_element_error_file.md) + - [PassportElementErrorFiles](passport_element_error_files.md) + - [PassportElementErrorTranslationFile](passport_element_error_translation_file.md) + - [PassportElementErrorTranslationFiles](passport_element_error_translation_files.md) + - [PassportElementErrorUnspecified](passport_element_error_unspecified.md) +* Games + - [Game](game.md) + - [CallbackGame](callback_game.md) + - [GameHighScore](game_high_score.md) diff --git a/docs/index.md b/docs/index.md index de65b474..c5652793 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ Documentation for version 3.0 [WIP] [^1] [![MIT License](https://img.shields.io/pypi/l/aiogram.svg?style=flat-square)](https://opensource.org/licenses/MIT) [![Supported python versions](https://img.shields.io/pypi/pyversions/aiogram.svg?style=flat-square)](https://pypi.python.org/pypi/aiogram) -[![Telegram Bot API](https://img.shields.io/badge/Telegram%20Bot%20API-4.6-blue.svg?style=flat-square&logo=telegram)](https://core.telegram.org/bots/api) +[![Telegram Bot API](https://img.shields.io/badge/Telegram%20Bot%20API-{!_api_version.md!}-blue.svg?style=flat-square&logo=telegram)](https://core.telegram.org/bots/api) [![PyPi Package Version](https://img.shields.io/pypi/v/aiogram.svg?style=flat-square)](https://pypi.python.org/pypi/aiogram) [![PyPi status](https://img.shields.io/pypi/status/aiogram.svg?style=flat-square)](https://pypi.python.org/pypi/aiogram) [![Downloads](https://img.shields.io/pypi/dm/aiogram.svg?style=flat-square)](https://pypi.python.org/pypi/aiogram) @@ -16,7 +16,7 @@ Documentation for version 3.0 [WIP] [^1] ## Features - Asynchronous -- [Supports Telegram Bot API v4.6](api/index.md) +- [Supports Telegram Bot API v{!_api_version.md!}](api/index.md) - [Updates router](dispatcher/index.md) (Blueprints) - Finite State Machine - Middlewares @@ -50,9 +50,7 @@ class MyHandler(MessageHandler): """ async def handle(self): - await self.bot.send_message( - chat_id=self.chat.id, text=f"Hello, {self.from_user.full_name}!" - ) + await self.event.answer(f"Hello, {self.from_user.full_name}!") @dp.message_handler(content_types=[types.ContentType.ANY]) diff --git a/mkdocs.yml b/mkdocs.yml index e54a48be..51bb1905 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,8 @@ markdown_extensions: emoji_generator: !!python/name:pymdownx.emoji.to_svg - pymdownx.tasklist - pymdownx.inlinehilite + - markdown_include.include: + base_path: docs nav: - index.md diff --git a/poetry.lock b/poetry.lock index f531dc80..79421824 100644 --- a/poetry.lock +++ b/poetry.lock @@ -381,6 +381,17 @@ setuptools = ">=36" [package.extras] testing = ["coverage", "pyyaml"] +[[package]] +category = "dev" +description = "This is an extension to Python-Markdown which provides an \"include\" function, similar to that found in LaTeX (and also the C pre-processor and Fortran). I originally wrote it for my FORD Fortran auto-documentation generator." +name = "markdown-include" +optional = false +python-versions = "*" +version = "0.5.1" + +[package.dependencies] +markdown = "*" + [[package]] category = "dev" description = "Safely add untrusted strings to HTML/XML markup." @@ -890,7 +901,7 @@ docs = ["sphinx", "jaraco.packaging (>=3.2)", "rst.linker (>=1.9)"] fast = ["uvloop"] [metadata] -content-hash = "a6934a2bb02c0e5963cc81c2cb797dfa6d78db714a40cd09b181c20c4a575a07" +content-hash = "2eb50b5b57d0fac4780f1eb3f92ff129d891fd346e0c00856c1a56c58feffb03" python-versions = "^3.7" [metadata.files] @@ -1086,6 +1097,9 @@ markdown = [ {file = "Markdown-3.1.1-py2.py3-none-any.whl", hash = "sha256:56a46ac655704b91e5b7e6326ce43d5ef72411376588afa1dd90e881b83c7e8c"}, {file = "Markdown-3.1.1.tar.gz", hash = "sha256:2e50876bcdd74517e7b71f3e7a76102050edec255b3983403f1a63e7c8a41e7a"}, ] +markdown-include = [ + {file = "markdown-include-0.5.1.tar.gz", hash = "sha256:72a45461b589489a088753893bc95c5fa5909936186485f4ed55caa57d10250f"}, +] markupsafe = [ {file = "MarkupSafe-1.1.1-cp27-cp27m-macosx_10_6_intel.whl", hash = "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161"}, {file = "MarkupSafe-1.1.1-cp27-cp27m-manylinux1_i686.whl", hash = "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7"}, diff --git a/pyproject.toml b/pyproject.toml index 0e627107..119fe577 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -61,6 +61,7 @@ pygments = "^2.4" pymdown-extensions = "^6.1" lxml = "^4.4" ipython = "^7.10" +markdown-include = "^0.5.1" [tool.poetry.extras] fast = ["uvloop"]