Title: Make documentation more accessible · Issue #2633 · python-telegram-bot/python-telegram-bot · GitHub
Open Graph Title: Make documentation more accessible · Issue #2633 · python-telegram-bot/python-telegram-bot
X Title: Make documentation more accessible · Issue #2633 · python-telegram-bot/python-telegram-bot
Description: 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 a...
Open Graph Description: 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 t...
X Description: 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 presenti...
Opengraph URL: https://github.com/python-telegram-bot/python-telegram-bot/issues/2633
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Make documentation more accessible","articleBody":"Hello world.\r\n\r\nWe 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.\r\n\r\nOne 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.\r\n\r\n**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.\r\n\r\nThe mentioned ideas:\r\n\r\n- [x] Cross referencing. a LOT: -> #3110\r\n - [ ] 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 #2855\r\n - [ ] examples + RTD -> wiki: JobQueue -> wiki/jobqueue, Bot.arbitrary_callback_data -> wiki/arbitrary_callback_data. examples/timerbot -> jobqueue. etc.\r\n - [ ] RT + wiki -> examples. JobQueue -> timerbot.py, wiki/jobqueue -> timerbot.py etc.\r\n\r\n These should help a great deal when it comes to \"where do I use this\"? or \"how is this used\"?\r\n- [ ] 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\r\n- [ ] 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 sphinx-doc/sphinx#9939. If/when this can be tackled, this should include the following:\r\n - [x] Unify documentation on how to pass files. Some of the classes/methods that accept file input have a note like [here](https://python-telegram-bot.readthedocs.io/en/stable/telegram.bot.html#telegram.Bot.send_document), 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](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Code-snippets#working-with-files-and-media) to a standalone page, extend it a bit and point to it from the docs. -> #3114\r\n - [x] Add a note to all Bot.edit_* methods that states the limitation about editing messages from the official docs: -> #3111\r\n > Please note, that it is currently only possible to edit messages without reply_markup or with inline keyboards.\r\n- [x] 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 #2770\r\n- [x] Add valuable information to attribute docstrings of telegram classes https://github.com/python-telegram-bot/python-telegram-bot/issues/2633#issuecomment-1041427149 -> #3109\r\n- [x] Think about making use of [`blacken-docs`](https://github.com/asottile/blacken-docs) Edit: Currently is not easy to integrate into workflow. not overly important anyway.\r\n- [x] List changelog in the resources in the readme #3103\r\n- [x] Make documentation about the \"bots default timezone\" more explicit - i.e. explain better that naive (date)time objects will usually be interpreted as UTC #3103\r\n- [x] Update docstrings of attributes which are a list, but may be empty. See https://github.com/python-telegram-bot/python-telegram-bot/pull/2741#issuecomment-1001740609 #3057\r\n- [x] Find a way to document Generic classes better, i.e. document which types they need to be fully annotated\r\n- [x] 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.\r\n- [x] In the docstrings of `Update.effective_*`, explicitly explain what those attributes will be set to. See https://github.com/python-telegram-bot/python-telegram-bot/issues/2826#issuecomment-1001151183\r\n- [x] 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. #2739\r\n- [x] 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 …\r\n- [x] Document that `TelegramObject` is subsriptable\r\n- [x] Ideas for catching errors in documentation faster and easier: #2798\r\n - [x] Enable the [nitpicky](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky) option. We can do this after we enable `intersphinx` since there are lots of 'warnings' now #2798\r\n - [x] add a workflow that builds the docs and checks for warnings & errors #2798\r\n- [x] Make parameters referencable with the `sphinx-paramlinks` extension #2798\r\n\r\n_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!_\r\n\r\n\r\nIf 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](/python-telegram-bot/python-telegram-bot/tree/doc-fixes) branch.","author":{"url":"https://github.com/Bibo-Joshi","@type":"Person","name":"Bibo-Joshi"},"datePublished":"2021-08-18T21:13:25Z","url":"https://github.com/python-telegram-bot/python-telegram-bot/issues/2633"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:506d3ac8-c951-609e-514e-4718547f3dc8 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | B338:1F927B:29AB72D:36891A2:6B026CBA |
| html-safe-nonce | 9e97e24cfc6d0cdf25a05a577e1c953b1ca4f4dd528a119c2ada00d3ed4d8ad0 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCMzM4OjFGOTI3QjoyOUFCNzJEOjM2ODkxQTI6NkIwMjZDQkEiLCJ2aXNpdG9yX2lkIjoiMzEyMDQzMzkzMDA3MTg2MjQ1OCIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | ba357b96142ca8837af41a35b589ef1af00429aea2e2f30104ba889d54e7ae68 |
| hovercard-subject-tag | issue:974060979 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python-telegram-bot/python-telegram-bot/2633/issue_layout |
| twitter:image | https://opengraph.githubassets.com/c067bac622c1309acb26231fd3ca456dc19dfddc765073790e83908b40ec13e0/python-telegram-bot/python-telegram-bot/issues/2633 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/c067bac622c1309acb26231fd3ca456dc19dfddc765073790e83908b40ec13e0/python-telegram-bot/python-telegram-bot/issues/2633 |
| og:image:alt | 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 t... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | Bibo-Joshi |
| hostname | github.com |
| expected-hostname | github.com |
| None | 87e774ee7c6b3bee0490394e4d3e57ec9dbc956f74b87ea685dc8996c1676456 |
| turbo-cache-control | no-preview |
| go-import | github.com/python-telegram-bot/python-telegram-bot git https://github.com/python-telegram-bot/python-telegram-bot.git |
| octolytics-dimension-user_id | 16178365 |
| octolytics-dimension-user_login | python-telegram-bot |
| octolytics-dimension-repository_id | 38696925 |
| octolytics-dimension-repository_nwo | python-telegram-bot/python-telegram-bot |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 38696925 |
| octolytics-dimension-repository_network_root_nwo | python-telegram-bot/python-telegram-bot |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 423dbb54c5e7bfecc838eb387c1435eb3d0e760d |
| ui-target | canary-1 |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width