Docs cross references (#2633) #2855

pavel-ignatovich · 2022-01-11T17:57:43Z

At the moment, only the first part of the cross-referencing task has been completed, related to links within the source code, excluding the wiki and examples.

Checklist for PRs

Added .. versionadded:: version, .. versionchanged:: version or .. deprecated:: version to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
Created new or adapted existing unit tests
Added myself alphabetically to AUTHORS.rst (optional)
Added new classes & modules to the docs

…ryptionError (#2621)

Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>

Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>

Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>

Signed-off-by: starry69 <starry369126@outlook.com> Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>

Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>

#2657)

Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>

Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: poolitzer <25934244+Poolitzer@users.noreply.github.com>

Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>

Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com> Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>

Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>

Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>

github-actions

Hey! Looks like you edited the (dev) requirements or the pre-commit hooks. I'm just a friendly reminder to keep the pre-commit hook versions in sync with the dev requirements and the additional dependencies for the hooks in sync with the requirements :)

github-actions

Hey! Looks like you edited README.rst or README_RAW.rst. I'm just a friendly reminder to apply relevant changes to both of those files :)

github-actions

Hey there. Relax, I am just a little warning for the maintainers to release directly after merging your PR, otherwise we have broken examples and people might get confused :)

Add references missed in 115573e

Bibo-Joshi

Thanks a lot for your PR - nice work! Concentrating on inter-doc linking is perfectly fine 👍
I left a few comments below. Apart from that, I have two more general comments:

it would be nice to have some more cross-referencing in tg.ext. e.g. link from Handler to Dispatcher.add/remove_handler, from CallbackContext.job to JobQueue, from {CallbackContext, Dispatcher.{chat, bot, user}_data} to ContextTypes, from ContextTypes to {Updater,Dispatcher}Builder.context_types, from Defaults to {Updater, Dispatcher}Builder.defaults and ExtBot.defaults, from CallbackDataCache to ExtBot.callback_data_cache and CallbackContext.drop_callback_data, from Dispatcher.update_persistence to BasePersistecne.update_*_data. You can probably find some more :) That said, I'm ofc aware, that it's probably impossible to find all the links :D
Having each reference on a new line seems a bit excessive and uses a lot of space. Can you remove the empty lines and add commas at the end of the lines? that way we get a more compact overview

Bibo-Joshi · 2022-01-11T20:40:42Z

telegram/_bot.py

@@ -2345,6 +2460,12 @@ def get_file(
             You should save the file's MIME type and name (if available) when the File object
             is received.

+        .. seealso:: :meth:`telegram.ChatPhoto.get_small_file`


here, we also have {Animation, Audio, Document, PhotoSize, Sticker, Video, VideoNote, Voice}.get_file. Please also check that you link back to here from those methods :)

Bibo-Joshi · 2022-01-11T20:45:37Z

telegram/_chatmember.py

@@ -42,6 +42,10 @@ class ChatMember(TelegramObject):
    Objects of this class are comparable in terms of equality. Two objects of this class are
    considered equal, if their :attr:`user` and :attr:`status` are equal.

+    .. seealso:: :attr:`telegram.ChatMemberUpdated.old_chat_member`


also tg.ChatMember, Bot.get_chat_member, Bot.get_chat_administrators

Bibo-Joshi · 2022-01-11T20:47:34Z

telegram/_chatpermissions.py

@@ -36,6 +36,8 @@ class ChatPermissions(TelegramObject):
        permissions that are set, but also sets all the others to :obj:`False`. However, since not
        documented, this behaviour may change unbeknown to PTB.

+    .. seealso:: :attr:`telegram.Chat.permissions`


and Bot.set_chat_permissions

Bibo-Joshi · 2022-01-11T20:48:05Z

telegram/_files/chatphoto.py

@@ -34,6 +34,8 @@ class ChatPhoto(TelegramObject):
    considered equal, if their :attr:`small_file_unique_id` and :attr:`big_file_unique_id` are
    equal.

+    .. seealso:: :attr:`telegram.Chat.ChatPhoto`


Suggested change

.. seealso:: :attr:`telegram.Chat.ChatPhoto`

.. seealso:: :attr:`telegram.Chat.chat_photo`

Bibo-Joshi · 2022-01-11T20:50:48Z

telegram/_files/inputmedia.py

+    .. seealso:: :attr:`telegram.CallbackQuery.media`
+
+        :attr:`telegram.messages.media`
+


InputMedia objects are never sent back from telegram, they are only used as input for send_media_group or edit_message_media. Please also add this to the subclasses - btw same for ChatMember :)

Bibo-Joshi · 2022-01-11T20:52:19Z

telegram/_keyboardbutton.py

@@ -39,6 +39,7 @@ class KeyboardButton(TelegramObject):
        * :attr:`request_poll` option will only work in Telegram versions released after 23
          January, 2020. Older clients will receive unsupported message.

+    .. seealso:: :attr:`telegram.ReplyKeyboardMarkup.keyboard`


Suggested change

.. seealso:: :attr:`telegram.ReplyKeyboardMarkup.keyboard`

.. seealso:: :attr:`telegram.ReplyKeyboardMarkup.keyboard`

Bibo-Joshi · 2022-01-11T20:53:59Z

telegram/_message.py

@@ -84,6 +84,22 @@ class Message(TelegramObject):
    Note:
        In Python :keyword:`from` is a reserved word, use ``from_user`` instead.

+    .. seealso:: :meth:`telegram.Bot.send_message`


all the other send_* methods also return Messages and so do the edit_* methods … IMO that's in fact a bit much cross referencing - IMO we can just skip all of those here, including send_message

Bibo-Joshi · 2022-01-11T20:57:04Z

telegram/ext/_basepersistence.py

@@ -96,6 +98,10 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
    .. versionchanged:: 14.0
        The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`.

+    .. seealso:: :attr:`telegram.ext.ConversationHandler.persistence`
+
+        :attr:`telegram.ext.Dispatcher.persistence`


{Updater, Dispatcher}Builder.persistence

Bibo-Joshi · 2022-01-11T20:58:15Z

telegram/ext/_builders.py

@@ -503,6 +503,8 @@ class DispatcherBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
    .. seealso::
        :class:`telegram.ext.UpdaterBuilder`

+        :meth:`telegram.ext.Dispatcher.builder`


this doesn' make much sense IMO, please remove. same below.

harshil21 · 2022-01-12T09:30:31Z

Wow, do we really need so many cross references? Can't imagine adding/maintaining each one of these after refactors/API updates

harshil21 · 2022-01-12T09:31:05Z

telegram/_user.py

+        :attr:`telegram.InlineQuery.from_user`
+
+        :attr:`telegram.InlineQuery.from_user`


harshil21 · 2022-01-12T09:33:10Z

telegram/_payment/labeledprice.py

+    .. seealso:: :attr:`telegram.InputInvoiceMessageContent.prices`
+
+        .. seealso:: :attr:`telegram.ShippingOption.prices`


Suggested change

.. seealso:: :attr:`telegram.InputInvoiceMessageContent.prices`

.. seealso:: :attr:`telegram.ShippingOption.prices`

.. seealso:: :attr:`telegram.InputInvoiceMessageContent.prices`,

:attr:`telegram.ShippingOption.prices`

Bibo-Joshi · 2022-01-12T09:56:18Z

Wow, do we really need so many cross references? Can't imagine adding/maintaining each one of these after refactors/API updates

Some are surely more useful than others. E.g. Linking from ReplyMarkup to Message.reply_markup etc has surely lesser value than linking from Bot.send_message to Message.reply_text & friends. But having it also doesn't hurt.
And especially for the pure API part I'd be okay if we don't catch everything always.

pavel-ignatovich · 2022-01-12T12:21:58Z

Thanks for feedback! I will be working on fixes of issues listed in comments in the coming days =)

Bibo-Joshi and others added 30 commits January 3, 2022 09:42

Temporarily enable tests for the v14 branch

1d15797

Move and Rename TelegramDecryptionError to telegram.error.PassportDec…

a3a5a53

…ryptionError (#2621)

Add Code Comment Guidelines to Contribution Guide (#2612)

c5e870d

Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>

Improve Type Hinting for CallbackContext (#2587)

2725a45

Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>

Add Custom pytest Marker to Ease Development (#2628)

220c28e

Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>

Make BasePersistence Methods Abstract (#2624)

62e9a48

Signed-off-by: starry69 <starry369126@outlook.com> Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>

Refactor Initialization of Persistence Classes (#2604)

21f424b

Remove __dict__ from __slots__ and drop Python 3.6 (#2619, #2636)

3edc362

Remove day_is_strict argument of JobQueue.run_monthly (#2634)

f84d78f

Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>

Drop Non-CallbackContext API (#2617)

ffde640

Fix Signatures and Improve test_official (#2643)

6dc7edf

Remove Deprecated Functionality (#2644, #2740, #2745)

1cabf11

Add User Friendly Type Check For Init Of {Inline, Reply}KeyboardMarkup (

fbc9c6b

#2657)

Refine Dispatcher.dispatch_error (#2660)

96d3ff4

Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>

Warnings Overhaul (#2662)

3004d69

Clear Up Import Policy (#2671)

bd310ec

Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>

Make InlineQuery.answer Raise ValueError (#2675)

5e98ffb

Doc Fixes (#2597)

dc478d9

Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: poolitzer <25934244+Poolitzer@users.noreply.github.com>

Move Defaults to telegram.ext (#2648)

0c4580c

Update Notification Workflows (#2695)

aadf860

Pass Failing Jobs to Error Handlers (#2692)

2d387b2

Improve Signature Inspection for Bot Methods (#2686)

7ae414e

Handle Filepaths via the Pathlib Module (#2688)

6ff1cad

Add Filters.update.edited (#2705)

7794f07

Use Error Messages for Pylint Instead of Codes (#2700)

d845228

Introduce Builder Pattern for Updater and Dispatcher (#2646)

56e758a

Mark Internal Modules As Private (#2687)

f2b3e9d

Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>

Accept File Paths for Updater/DispatcherBuilder.private_key (#2724)

6c858e6

Make Tests Agnostic of the CWD (#2727)

d14385e

Refactor MRO of InputMedia* and Some File-Like Classes (#2717)

cda3a49

Bibo-Joshi and others added 11 commits January 3, 2022 10:03

Improve Code Quality (#2783)

bfeb2f3

Improve Subscription of TelegramObject (#2719)

59b2fdf

Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com> Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>

Update pre-commit Settings & Improve a Test (#2796)

4a9c2c0

Convenience Functionality for ChatInviteLinks (#2782)

eb0b0f3

Use __all__ Consistently (#2805)

87ad804

Documentation Improvements (#2693, #2691, #2739)

c34ded4

Improve Error Messages in CommandHandler.__init__ (#2837)

fad85b7

Add Dispatcher.add_handlers (#2823)

38ce266

Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>

Improve Job.__getattr__ (#2832)

5f43705

Documentation Fixes & Improvements (#2822)

d66297e

Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>

Switch Sphinx Theme to Furo (#2841)

d4a2e40

github-actions bot reviewed Jan 11, 2022

View reviewed changes

pavel-ignatovich added 3 commits January 11, 2022 21:16

Add cross-referencing to telegram package (#2633)

845c2d0

Add cross-referencing to telegram module (#2633)

661eb5f

Add references missed in 115573e

Cross-referencing at telegram.ext module (#2633)

1291695

Bibo-Joshi mentioned this pull request Jan 11, 2022

Make documentation more accessible #2633

Closed

24 tasks

Bibo-Joshi requested changes Jan 11, 2022

View reviewed changes

harshil21 reviewed Jan 12, 2022

View reviewed changes

harshil21 added this to the v14 milestone Jan 12, 2022

harshil21 added the ⚙️ documentation affected functionality: documentation label Jan 12, 2022

harshil21 added the 📋 pending-reply work status: pending-reply label Feb 1, 2022

Bibo-Joshi force-pushed the doc-fixes branch from 9afa8af to fa4f8af Compare February 6, 2022 09:53

Bibo-Joshi deleted the branch python-telegram-bot:doc-fixes February 9, 2022 16:30

Bibo-Joshi closed this Feb 9, 2022

github-actions bot locked and limited conversation to collaborators Feb 16, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs cross references (#2633) #2855

Docs cross references (#2633) #2855

pavel-ignatovich commented Jan 11, 2022

github-actions bot left a comment

github-actions bot left a comment

github-actions bot left a comment

Bibo-Joshi left a comment

Bibo-Joshi Jan 11, 2022

Bibo-Joshi Jan 11, 2022

Bibo-Joshi Jan 11, 2022

Bibo-Joshi Jan 11, 2022

Bibo-Joshi Jan 11, 2022

Bibo-Joshi Jan 11, 2022

Bibo-Joshi Jan 11, 2022

Bibo-Joshi Jan 11, 2022

Bibo-Joshi Jan 11, 2022

harshil21 commented Jan 12, 2022

harshil21 Jan 12, 2022

harshil21 Jan 12, 2022

Bibo-Joshi commented Jan 12, 2022

pavel-ignatovich commented Jan 12, 2022 •

edited

Loading

	.. seealso:: :attr:`telegram.Chat.ChatPhoto`
	.. seealso:: :attr:`telegram.Chat.chat_photo`

		.. seealso:: :attr:`telegram.CallbackQuery.media`

		:attr:`telegram.messages.media`

	.. seealso:: :attr:`telegram.ReplyKeyboardMarkup.keyboard`
	.. seealso:: :attr:`telegram.ReplyKeyboardMarkup.keyboard`

		:attr:`telegram.InlineQuery.from_user`

		:attr:`telegram.InlineQuery.from_user`

		.. seealso:: :attr:`telegram.InputInvoiceMessageContent.prices`

		.. seealso:: :attr:`telegram.ShippingOption.prices`

Docs cross references (#2633) #2855

Docs cross references (#2633) #2855

Conversation

pavel-ignatovich commented Jan 11, 2022

Checklist for PRs

github-actions bot left a comment

Choose a reason for hiding this comment

github-actions bot left a comment

Choose a reason for hiding this comment

github-actions bot left a comment

Choose a reason for hiding this comment

Bibo-Joshi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

harshil21 commented Jan 12, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Bibo-Joshi commented Jan 12, 2022

pavel-ignatovich commented Jan 12, 2022 • edited Loading

pavel-ignatovich commented Jan 12, 2022 •

edited

Loading