Hello world.

We receive regularly queries in our help group from people unable to read the support documents we provide. We believe this is mainly because we don't do a good enough job presenting them. This is where you come in: If you are new to the project and think "hey, this can be improved", and its not on the list yet, tell us about this.

One maintainer has compromised the thoughts we as maintainers made about this topic, but we value foreign input very much. Some discussion about this happened at https://t.me/pythontelegrambotgroup/504413 + answers.

edit: The list was extended with the ideas from the comments below and converted into a checklist so that it's easier to keep track of what's already been done.

The mentioned ideas:

• Cross referencing. a LOT: -> [Documentation] Add more cross-references #3110

  • within RTD: JobQueue -> CallbackContext.job_queue, Dispatcher.job_queue, Updater.job_queue. Bot.edit_message_text -> Message.edit_text. Similar for all other stuff that makes sense - bascically all "where is this used" references. sphinx has the nice .. seealso:: directive that we can use for this Docs cross references (#2633) #2855
  • examples + RTD -> wiki: JobQueue -> wiki/jobqueue, Bot.arbitrary_callback_data -> wiki/arbitrary_callback_data. examples/timerbot -> jobqueue. etc.
  • RT + wiki -> examples. JobQueue -> timerbot.py, wiki/jobqueue -> timerbot.py etc.

  These should help a great deal when it comes to "where do I use this"? or "how is this used"?

• Maybe: On RTD, for the really newbies a "how to read sphinx docs", e.g. explain that "Parameters: token (str) – Bot’s unique authentication." means that the keyword argument ist named "token" and expects input of type str

• We have several notes and docstrings that are repeated very often across the docs, which makes it hard to maintain them. An idea is to use the .. include:: directive to unify those. Unfortunately this currently doesn't work with the napoleon docstring style that we use - see Resolve directives before running napoleon sphinx-doc/sphinx#9939. If/when this can be tackled, this should include the following:

  • Unify documentation on how to pass files. Some of the classes/methods that accept file input have a note like here, but others don't. Also that note is outdated, as it doesn't explain when a pathlib.Path can be passed. It should also mention that we don't support open(file, 'r') but only open(file, 'rb'). We should either have a unified note that we add everywhere or move this snippets section to a standalone page, extend it a bit and point to it from the docs. -> [Feature] Improve handling of local mode & docs regarding file handling #3114
  • Add a note to all Bot.edit_* methods that states the limitation about editing messages from the official docs: -> [Documentation] Add note on editing with reply markups #3111

    Please note, that it is currently only possible to edit messages without reply_markup or with inline keyboards.

• Improve docs of ConversationHandler regarding the TIMEOUT & WAITING state, probably including a small code example. This is one of the things that in my experience users have the hardest time to grasp. -> let's do this in the context of [Discussion:] ConversationHandler #2770

• Add valuable information to attribute docstrings of telegram classes Make documentation more accessible #2633 (comment) -> [Documentation] Add valuable information to attribute docstrings of telegram classes #3109

• Think about making use of blacken-docs Edit: Currently is not easy to integrate into workflow. not overly important anyway.

• List changelog in the resources in the readme Documentation Improvements #3103

• Make documentation about the "bots default timezone" more explicit - i.e. explain better that naive (date)time objects will usually be interpreted as UTC Documentation Improvements #3103

• Update docstrings of attributes which are a list, but may be empty. See Update _message.py - issue #2606 #2741 (comment) Empty lists #3057

• Find a way to document Generic classes better, i.e. document which types they need to be fully annotated

• On the start page of RTD, the wiki, the examples folder & the GH readme, explain better what the different resources cover. RTD covers technical reference, i.e. comprehensive but not too elaborate, wiki explains certain features in detail, examples do minimal code showcases with little explanation. I imagine a somewhat unified text like "You're at the examples page, which gives you minimal code showcases for PTB features. For detailed tutorials on certain PTB features, please head to the wiki. …" and similar for the other resources.

• In the docstrings of Update.effective_*, explicitly explain what those attributes will be set to. See [FEATURE] A function to automatically decide if update.message.reply_text or update.callback_query.edit_message_text will be used. #2826 (comment)

• Link classes to python to docs. in the above mentioned thread, the user was not aware how to build a datetime object and tbh one can't expect newbies to know about all python std-libs. in sphinx it's rather easy to cross-ref to other sphinx docs, so let's do that. Docs link python classes to docs #2633 #2739

• get rid of all the JSON-serialized that we copied from the offiicial docs - PTB users never encounter JSON-serialized objects. I think we briefly discussed this at some point but never acted on it …

• Document that TelegramObject is subsriptable

• Ideas for catching errors in documentation faster and easier: Docs improvements: referencing #2798

  • Enable the nitpicky option. We can do this after we enable intersphinx since there are lots of 'warnings' now Docs improvements: referencing #2798
  • add a workflow that builds the docs and checks for warnings & errors Docs improvements: referencing #2798

• Make parameters referencable with the sphinx-paramlinks extension Docs improvements: referencing #2798

Documentation is a great place to get started contributing to Open Source projects without having to write/dive deep into the complex code making up this project. If you look for an "easy" way to give back to the OS community this October, this might be it!

If you like to start working on one of the ideas, comment on this issue as well and say what you want to work on. Once you are ready to show your changes, open a PR towards the doc-fixes branch.