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 label Jan 12, 2022

harshil21 added the 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

	.. 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

pavel-ignatovich commented Jan 12, 2022 •

edited