Let's discuss documenation

[elebur]

One of the things I like most about the PTB is its documentation. This is one of the best documentation I've ever worked with! And I want PTBTest to have such documentation too.

I think we need to develop a style guide for docstrings so that the documentation is consistent across the project.

Right now, I'm working on the documentation for the EntityParser. Here is an example of docstrings for the module:

This module provides a helper class to transform
marked-up messages to plain text and a :obj:`tuple` of
:class:`entities <telegram.MessageEntity>`.

`Telegram Docs <https://core.telegram.org/bots/api#formatting-options>`_

And here is an example for the get_item function:

    Safely gets item from the sequence by its index.
    If the ``index`` is out of the range, then the ``default`` value is returned.

    :param seq: (`type`: :obj:`~collections.abc.Sequence`) A sequence to get the item from.
    :param index: (`type`: :obj:`int`) An item's index.
    :param default: (`type`: :obj:`~typing.Any`) The value to be returned if the
        ``index`` is out of the range, defaults to :obj:`None`.
    :return: (`type`: :obj:`~typing.Any`) An item under the given ``index`` or
        the ``default`` value.

And here is how these docstrings are rendered:

tuple, entities, Sequence, Any, None, int are links to the objects.

---

The general template I'm using right now is the next:

Description of a method/funtion

    :param one: (`type`: :obj:`type.of.param`) The param description
    :return: (`type`: :obj:`type.of.return.value`) A return value description.

• Use cross reference. E.g. if MessageEntity is mentioned it must be a link to the PTB's documentation:
  The function returns :obj:`telegram.MessageEntity`

---

What would you say?

[elebur]

PTB uses Google Style Docstrings, which I think is nicer and easier to read.

Example

      Use this method to delete a message, including service messages, with the following
      limitations:

      Note:
          The method CallbackQuery.delete_message() will not be found when automatically
          generating "Shortcuts" admonitions for Bot methods because it has no calls
          to Bot methods in its return statement(s). So it is manually included in "See also".

      .. seealso::
          :meth:`telegram.CallbackQuery.delete_message` (calls :meth:`delete_message`
          indirectly, via :meth:`telegram.Message.delete`)

      Args:
          chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
          message_id (:obj:`int`, optional): Identifier of the message to delete.

      Returns:
          :obj:`bool`: On success, :obj:`True` is returned.

      Raises:
          :class:`telegram.error.TelegramError`

[AlexPHorta]

Yes, I like the Google Style too. We could use it, and "translate" the already existent documentation to its standard. For me, it's ok.

[AlexPHorta]

By the way, check the documentation website, in the 'latest' version.

[elebur]

Yes, I like the Google Style too. We could use it, and "translate" the already existent documentation to its standard. For me, it's ok.

Great! I'm already working on the documentation for the entityparser module. Once you approve my recent PR, I'll send a new one with updated docstrings.

By the way, check the documentation website, in the 'latest' version.

Yes, saw it 👍
I added a few little changes to the documentation's appearance:

1. Removed the full path (with a package and module) of the function. E.g., instead of ptbtest.entityparser.get_item() now it is get_item().
2. Removed printing of type hints.

You can see what it looks like in the screenshot from my first message in this discussion and compare it with the current appearance.