Small documentation improvements and texts update

aiogram · Aug 26, 2023 · ca4c1b4 · ca4c1b4
1 parent 806f8f6
commit ca4c1b4
Show file tree

Hide file tree

Showing 41 changed files with 2,156 additions and 1,163 deletions.
diff --git a/README.rst b/README.rst
@@ -56,7 +56,7 @@ Features
 - Telegram Bot API integration code was `autogenerated <https://github.com/aiogram/tg-codegen>`_ and can be easily re-generated when API gets updated
 - Updates router (Blueprints)
 - Has Finite State Machine
-- Uses powerful `magic filters <https://docs.aiogram.dev/en/dev-3.x/dispatcher/filters/magic_filters.html#magic-filters>`
+- Uses powerful `magic filters <https://docs.aiogram.dev/en/latest/dispatcher/filters/magic_filters.html#magic-filters>`_
 - Middlewares (incoming updates and API calls)
 - Provides `Replies into Webhook <https://core.telegram.org/bots/faq#how-can-i-make-requests-in-response-to-updates>`_
 - Integrated I18n/L10n support with GNU Gettext (or Fluent)

diff --git a/docs/dispatcher/dispatcher.rst b/docs/dispatcher/dispatcher.rst
@@ -6,8 +6,8 @@ Dispatcher is root :obj:`Router` and in code Dispatcher can be used directly for
 
 Here is only listed base information about Dispatcher. All about writing handlers, filters and etc. you can found in next pages:
 
-- `Router <router.html>`__
-- `Observer <observer.html>`__
+- :ref:`Router <Router>`
+- :ref:`Filtering events`
 
 
 .. autoclass:: aiogram.dispatcher.dispatcher.Dispatcher

diff --git a/docs/dispatcher/filters/callback_data.rst b/docs/dispatcher/filters/callback_data.rst
@@ -1,4 +1,4 @@
-.. _callback-data-factory
+.. _Callback data factory:
 
 ==============================
 Callback Data Factory & Filter

diff --git a/docs/dispatcher/filters/chat_member_updated.rst b/docs/dispatcher/filters/chat_member_updated.rst
@@ -2,6 +2,27 @@
 ChatMemberUpdated
 =================
 
+Usage
+=====
+
+Handle user leave or join events
+
+.. code-block:: python
+
+    from aiogram.filters import IS_MEMBER, IS_NOT_MEMBER
+
+    @router.chat_member(ChatMemberUpdatedFilter(IS_MEMBER >> IS_NOT_MEMBER))
+    async def on_user_leave(event: ChatMemberUpdated): ...
+
+    @router.chat_member(ChatMemberUpdatedFilter(IS_NOT_MEMBER >> IS_MEMBER))
+    async def on_user_join(event: ChatMemberUpdated): ...
+
+Or construct your own terms via using pre-defined set of statuses and transitions.
+
+
+Explanation
+===========
+
 .. autoclass:: aiogram.filters.chat_member_updated.ChatMemberUpdatedFilter
     :members:
     :member-order: bysource
@@ -77,22 +98,6 @@ will produce swap of old and new statuses.
     Note that if you define the status unions (via :code:`|`) you will need to add brackets for the statement
     before use shift operator in due to operator priorities.
 
-Usage
-=====
-
-Handle user leave or join events
-
-.. code-block:: python
-
-    from aiogram.filters import IS_MEMBER, IS_NOT_MEMBER
-
-    @router.chat_member(ChatMemberUpdatedFilter(IS_MEMBER >> IS_NOT_MEMBER))
-    async def on_user_leave(event: ChatMemberUpdated): ...
-
-    @router.chat_member(ChatMemberUpdatedFilter(IS_NOT_MEMBER >> IS_MEMBER))
-    async def on_user_join(event: ChatMemberUpdated): ...
-
-Or construct your own terms via using pre-defined set of statuses and transitions.
 
 Allowed handlers
 ================

diff --git a/docs/dispatcher/filters/command.rst b/docs/dispatcher/filters/command.rst
@@ -2,19 +2,6 @@
 Command
 =======
 
-.. autoclass:: aiogram.filters.command.Command
-    :members: __init__
-    :member-order: bysource
-    :undoc-members: False
-
-When filter is passed the :class:`aiogram.filters.command.CommandObject` will be passed to the handler argument :code:`command`
-
-.. autoclass:: aiogram.filters.command.CommandObject
-    :members:
-    :member-order: bysource
-    :undoc-members: False
-
-
 Usage
 =====
 
@@ -28,6 +15,19 @@ Usage
 
     Command cannot include spaces or any whitespace
 
+
+.. autoclass:: aiogram.filters.command.Command
+    :members: __init__
+    :member-order: bysource
+    :undoc-members: False
+
+When filter is passed the :class:`aiogram.filters.command.CommandObject` will be passed to the handler argument :code:`command`
+
+.. autoclass:: aiogram.filters.command.CommandObject
+    :members:
+    :member-order: bysource
+    :undoc-members: False
+
 Allowed handlers
 ================
 

diff --git a/docs/dispatcher/filters/index.rst b/docs/dispatcher/filters/index.rst
@@ -1,3 +1,5 @@
+.. _Filtering events:
+
 ================
 Filtering events
 ================

diff --git a/docs/dispatcher/filters/magic_data.rst b/docs/dispatcher/filters/magic_data.rst
@@ -2,6 +2,14 @@
 MagicData
 =========
 
+Usage
+=====
+
+#. :code:`MagicData(F.event.from_user.id == F.config.admin_id)`  (Note that :code:`config` should be passed from middleware)
+
+Explanation
+===========
+
 .. autoclass:: aiogram.filters.magic_data.MagicData
     :members:
     :member-order: bysource
@@ -11,11 +19,6 @@ Can be imported:
 
 - :code:`from aiogram.filters import MagicData`
 
-Usage
-=====
-
-#. :code:`MagicData(F.event.from_user.id == F.config.admin_id)`  (Note that :code:`config` should be passed from middleware)
-
 
 Allowed handlers
 ================

diff --git a/docs/dispatcher/finite_state_machine/index.rst b/docs/dispatcher/finite_state_machine/index.rst
@@ -1,3 +1,5 @@
+.. _Finite State Machine:
+
 ====================
 Finite State Machine
 ====================

diff --git a/docs/dispatcher/index.rst b/docs/dispatcher/index.rst
@@ -26,12 +26,12 @@ So, you can use both of them with *aiogram*.
 
     router
     dispatcher
-    class_based_handlers/index
+    dependency_injection
     filters/index
-    middlewares
-    finite_state_machine/index
-    flags
-    errors
     long_polling
     webhook
-    dependency_injection
+    finite_state_machine/index
+    middlewares
+    errors
+    flags
+    class_based_handlers/index
diff --git a/docs/dispatcher/router.rst b/docs/dispatcher/router.rst
@@ -1,7 +1,23 @@
+.. _Router:
+
 ######
 Router
 ######
 
+Usage:
+
+.. code-block:: python
+
+    from aiogram import Router
+    from aiogram.types import Message
+
+    my_router = Router(name=__name__)
+
+    @my_router.message()
+    async def message_handler(message: Message) -> Any:
+        await message.answer('Hello from my router!')
+
+
 .. autoclass:: aiogram.dispatcher.router.Router
     :members: __init__, include_router, include_routers, resolve_used_update_types
     :show-inheritance:

diff --git a/docs/install.rst b/docs/install.rst
@@ -24,7 +24,7 @@ From PyPI
 
 .. code-block:: bash
 
-    pip install -U --pre aiogram
+    pip install -U aiogram
 
 From GitHub
 -----------

diff --git a/docs/locale/en/LC_MESSAGES/api/methods/unpin_all_general_forum_topic_messages.po b/docs/locale/en/LC_MESSAGES/api/methods/unpin_all_general_forum_topic_messages.po
@@ -0,0 +1,94 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2023, aiogram Team
+# This file is distributed under the same license as the aiogram package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2023.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: aiogram \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2023-08-26 23:17+0300\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.12.1\n"
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:3
+msgid "unpinAllGeneralForumTopicMessages"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:5
+msgid "Returns: :obj:`bool`"
+msgstr ""
+
+#: aiogram.methods.unpin_all_general_forum_topic_messages.UnpinAllGeneralForumTopicMessages:1
+#: of
+msgid ""
+"Use this method to clear the list of pinned messages in a General forum "
+"topic. The bot must be an administrator in the chat for this to work and "
+"must have the *can_pin_messages* administrator right in the supergroup. "
+"Returns :code:`True` on success."
+msgstr ""
+
+#: aiogram.methods.unpin_all_general_forum_topic_messages.UnpinAllGeneralForumTopicMessages:3
+#: of
+msgid ""
+"Source: "
+"https://core.telegram.org/bots/api#unpinallgeneralforumtopicmessages"
+msgstr ""
+
+#: ../../docstring
+#: aiogram.methods.unpin_all_general_forum_topic_messages.UnpinAllGeneralForumTopicMessages.chat_id:1
+#: of
+msgid ""
+"Unique identifier for the target chat or username of the target "
+"supergroup (in the format :code:`@supergroupusername`)"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:15
+msgid "Usage"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:18
+msgid "As bot method"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:26
+msgid "Method as object"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:28
+msgid "Imports:"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:30
+msgid ""
+":code:`from aiogram.methods.unpin_all_general_forum_topic_messages import"
+" UnpinAllGeneralForumTopicMessages`"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:31
+msgid ""
+"alias: :code:`from aiogram.methods import "
+"UnpinAllGeneralForumTopicMessages`"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:34
+msgid "With specific bot"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:41
+msgid "As reply into Webhook in handler"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:49
+msgid "As shortcut from received object"
+msgstr ""
+
+#: ../../api/methods/unpin_all_general_forum_topic_messages.rst:51
+msgid ":meth:`aiogram.types.chat.Chat.unpin_all_general_forum_topic_messages`"
+msgstr ""
diff --git a/docs/locale/en/LC_MESSAGES/api/types/chat.po b/docs/locale/en/LC_MESSAGES/api/types/chat.po
@@ -8,14 +8,14 @@ msgid ""
 msgstr ""
 "Project-Id-Version: aiogram \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-03-11 01:52+0200\n"
+"POT-Creation-Date: 2023-08-26 23:17+0300\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"
 "Content-Transfer-Encoding: 8bit\n"
-"Generated-By: Babel 2.11.0\n"
+"Generated-By: Babel 2.12.1\n"
 
 #: ../../api/types/chat.rst:3
 msgid "Chat"
@@ -88,6 +88,13 @@ msgid ""
 ":class:`aiogram.methods.get_chat.GetChat`."
 msgstr ""
 
+#: ../../docstring aiogram.types.chat.Chat.emoji_status_expiration_date:1 of
+msgid ""
+"*Optional*. Expiration date of the emoji status of the other party in a "
+"private chat, if any. Returned only in "
+":class:`aiogram.methods.get_chat.GetChat`."
+msgstr ""
+
 #: ../../docstring aiogram.types.chat.Chat.bio:1 of
 msgid ""
 "*Optional*. Bio of the other party in a private chat. Returned only in "
@@ -264,6 +271,7 @@ msgstr ""
 #: aiogram.types.chat.Chat.set_sticker_set:4
 #: aiogram.types.chat.Chat.set_title:4 aiogram.types.chat.Chat.unban:4
 #: aiogram.types.chat.Chat.unban_sender_chat:4
+#: aiogram.types.chat.Chat.unpin_all_general_forum_topic_messages:4
 #: aiogram.types.chat.Chat.unpin_all_messages:4
 #: aiogram.types.chat.Chat.unpin_message:4 of
 msgid ":code:`chat_id`"
@@ -320,6 +328,7 @@ msgstr ""
 #: aiogram.types.chat.Chat.set_permissions aiogram.types.chat.Chat.set_photo
 #: aiogram.types.chat.Chat.set_sticker_set aiogram.types.chat.Chat.set_title
 #: aiogram.types.chat.Chat.unban aiogram.types.chat.Chat.unban_sender_chat
+#: aiogram.types.chat.Chat.unpin_all_general_forum_topic_messages
 #: aiogram.types.chat.Chat.unpin_all_messages
 #: aiogram.types.chat.Chat.unpin_message of
 msgid "Returns"
@@ -1269,6 +1278,33 @@ msgstr ""
 msgid "instance of method :class:`aiogram.methods.set_chat_photo.SetChatPhoto`"
 msgstr ""
 
+#: aiogram.types.chat.Chat.unpin_all_general_forum_topic_messages:1 of
+msgid ""
+"Shortcut for method "
+":class:`aiogram.methods.unpin_all_general_forum_topic_messages.UnpinAllGeneralForumTopicMessages`"
+" will automatically fill method attributes:"
+msgstr ""
+
+#: aiogram.types.chat.Chat.unpin_all_general_forum_topic_messages:6 of
+msgid ""
+"Use this method to clear the list of pinned messages in a General forum "
+"topic. The bot must be an administrator in the chat for this to work and "
+"must have the *can_pin_messages* administrator right in the supergroup. "
+"Returns :code:`True` on success."
+msgstr ""
+
+#: aiogram.types.chat.Chat.unpin_all_general_forum_topic_messages:8 of
+msgid ""
+"Source: "
+"https://core.telegram.org/bots/api#unpinallgeneralforumtopicmessages"
+msgstr ""
+
+#: aiogram.types.chat.Chat.unpin_all_general_forum_topic_messages:10 of
+msgid ""
+"instance of method "
+":class:`aiogram.methods.unpin_all_general_forum_topic_messages.UnpinAllGeneralForumTopicMessages`"
+msgstr ""
+
 #~ msgid ""
 #~ "Use this method to get information "
 #~ "about a member of a chat. The "