Sphinx restructuring: Now builds PDF and better HTML docs (#449)

* update sphinx source files to properly build latexpdf and improve html build

* fix docstrings and sphinx sources to get rid of warnings

* add telegram.contrib.rst
This commit is contained in:
Jannes Höke 2016-11-01 06:53:51 +01:00 committed by GitHub
parent b22c3cc5c0
commit aa3ca38837
42 changed files with 95 additions and 82 deletions

View file

@ -209,6 +209,9 @@ htmlhelp_basename = 'PythonTelegramBotdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
'preamble': '''\\setcounter{tocdepth}{2}
\\usepackage{enumitem}
\\setlistdepth{99}''',
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',

View file

@ -10,7 +10,7 @@ Contents:
telegram
.. toctree::
:maxdepth: 2
telegram

View file

@ -1,7 +0,0 @@
telegram
========
.. toctree::
:maxdepth: 4
telegram

View file

@ -0,0 +1,17 @@
telegram.contrib package
========================
Submodules
----------
.. toctree::
telegram.contrib.botan
Module contents
---------------
.. automodule:: telegram.contrib
:members:
:undoc-members:
:show-inheritance:

View file

@ -10,6 +10,7 @@ Submodules
telegram.ext.dispatcher
telegram.ext.jobqueue
telegram.ext.handler
telegram.ext.callbackqueryhandler
telegram.ext.choseninlineresulthandler
telegram.ext.conversationhandler
telegram.ext.commandhandler

View file

@ -1,5 +1,5 @@
telegram.inlinekeyboardbutton module
===========================
====================================
.. automodule:: telegram.inlinekeyboardbutton
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinekeyboardmarkup module
==========================
====================================
.. automodule:: telegram.inlinekeyboardmarkup
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultarticle module
=================================
========================================
.. automodule:: telegram.inlinequeryresultarticle
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultaudio module
=================================
======================================
.. automodule:: telegram.inlinequeryresultaudio
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultcachedaudio module
=================================
============================================
.. automodule:: telegram.inlinequeryresultcachedaudio
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultcacheddocument module
=================================
===============================================
.. automodule:: telegram.inlinequeryresultcacheddocument
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultcachedgif module
=================================
==========================================
.. automodule:: telegram.inlinequeryresultcachedgif
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultcachedmpeg4gif module
=================================
===============================================
.. automodule:: telegram.inlinequeryresultcachedmpeg4gif
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultcachedphoto module
=================================
============================================
.. automodule:: telegram.inlinequeryresultcachedphoto
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultcachedsticker module
=================================
==============================================
.. automodule:: telegram.inlinequeryresultcachedsticker
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultcachedvideo module
=================================
============================================
.. automodule:: telegram.inlinequeryresultcachedvideo
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultcachedvoice module
=================================
============================================
.. automodule:: telegram.inlinequeryresultcachedvoice
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultcontact module
=================================
========================================
.. automodule:: telegram.inlinequeryresultcontact
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultdocument module
=================================
=========================================
.. automodule:: telegram.inlinequeryresultdocument
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultgif module
=================================
====================================
.. automodule:: telegram.inlinequeryresultgif
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultlocation module
=================================
=========================================
.. automodule:: telegram.inlinequeryresultlocation
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultmpeg4gif module
=================================
=========================================
.. automodule:: telegram.inlinequeryresultmpeg4gif
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultphoto module
=================================
======================================
.. automodule:: telegram.inlinequeryresultphoto
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultvenue module
=================================
======================================
.. automodule:: telegram.inlinequeryresultvenue
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultvideo module
=================================
======================================
.. automodule:: telegram.inlinequeryresultvideo
:members:

View file

@ -1,5 +1,5 @@
telegram.inlinequeryresultvoice module
=================================
======================================
.. automodule:: telegram.inlinequeryresultvoice
:members:

View file

@ -1,7 +0,0 @@
telegram.nullhandler module
===========================
.. automodule:: telegram.nullhandler
:members:
:undoc-members:
:show-inheritance:

View file

@ -9,6 +9,8 @@ Submodules
telegram.audio
telegram.base
telegram.bot
telegram.constants
telegram.contrib
telegram.ext
telegram.inlinequery
telegram.inlinequeryresult
@ -37,14 +39,12 @@ Submodules
telegram.chataction
telegram.contact
telegram.document
telegram.emoji
telegram.error
telegram.forcereply
telegram.chat
telegram.inputfile
telegram.location
telegram.message
telegram.nullhandler
telegram.photosize
telegram.replykeyboardhide
telegram.replykeyboardmarkup

View file

@ -347,13 +347,13 @@ class Bot(TelegramObject):
Args:
chat_id: Unique identifier for the message recipient - Chat id.
audio Audio file to send. You can either pass a file_id as String to resend an audio
audio: Audio file to send. You can either pass a file_id as String to resend an audio
that is already on the Telegram servers, or upload a new audio file using
multipart/form-data.
duration (Optional[int]): Duration of sent audio in seconds.
performer: Performer of sent audio. [Optional]
title: Title of sent audio. [Optional]
caption: Audio caption [Optional]
performer (Optional[str]): Performer of sent audio.
title (Optional[str]): Title of sent audio.
caption (Optional[str]): Audio caption
disable_notification (Optional[bool]): Sends the message silently. iOS users will not
receive a notification, Android users will receive a notification with no sound.
reply_to_message_id (Optional[int]): If the message is a reply, ID of the original
@ -405,8 +405,8 @@ class Bot(TelegramObject):
chat_id: Unique identifier for the message recipient - Chat id.
document: File to send. You can either pass a file_id as String to resend a file that
is already on the Telegram servers, or upload a new file using multipart/form-data.
filename: File name that shows in telegram message (it is usefull when you send file
generated by temp module, for example). [Optional]
filename (Optional[str]): File name that shows in telegram message (it is usefull when
you send file generated by temp module, for example).
caption (Optional[str]): Document caption (may also be used when resending documents by
file_id), 0-200 characters.
disable_notification (Optional[bool]): Sends the message silently. iOS users will not
@ -554,7 +554,7 @@ class Bot(TelegramObject):
that is already on the Telegram servers, or upload a new audio file using
multipart/form-data.
duration (Optional[int]): Duration of sent audio in seconds.
caption: Voice caption [Optional]
caption (Optional[str]): Voice caption
disable_notification (Optional[bool]): Sends the message silently. iOS users will not
receive a notification, Android users will receive a notification with no sound.
reply_to_message_id (Optional[int]): If the message is a reply, ID of the original
@ -777,6 +777,7 @@ class Bot(TelegramObject):
chat_id: Unique identifier for the message recipient - Chat id.
action: Type of action to broadcast. Choose one, depending on what the user is about to
receive:
- ChatAction.TYPING for text messages,
- ChatAction.UPLOAD_PHOTO for photos,
- ChatAction.UPLOAD_VIDEO for videos,
@ -862,8 +863,8 @@ class Bot(TelegramObject):
Args:
user_id: Unique identifier of the target user.
offset (Optional[int]: Sequential number of the first photo to be returned. By default,
all photos are returned.
offset (Optional[int]): Sequential number of the first photo to be returned. By
default, all photos are returned.
limit (Optional[int]): Limits the number of photos to be retrieved. Values between
1-100 are accepted. Defaults to 100.
timeout (Optional[float]): If this value is specified, use it as the definitive timeout
@ -960,7 +961,7 @@ class Bot(TelegramObject):
Args:
chat_id: Unique identifier for the target group or username of the target supergroup
(in the format @supergroupusername).
user_id: Unique identifier of the target user.
user_id: Unique identifier of the target user.
timeout (Optional[float]): If this value is specified, use it as the definitive timeout
(in seconds) for urlopen() operations.
**kwargs (dict): Arbitrary keyword arguments.

View file

@ -39,7 +39,7 @@ class CallbackQueryHandler(Handler):
pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
be used to insert updates. Default is ``False``.
be used to insert updates. Default is ``False``.
pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
instance created by the ``Updater`` which can be used to schedule new jobs.

View file

@ -35,7 +35,7 @@ class ChosenInlineResultHandler(Handler):
pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
be used to insert updates. Default is ``False``.
be used to insert updates. Default is ``False``.
pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
instance created by the ``Updater`` which can be used to schedule new jobs.

View file

@ -44,7 +44,7 @@ class CommandHandler(Handler):
pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
be used to insert updates. Default is ``False``.
be used to insert updates. Default is ``False``.
pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
instance created by the ``Updater`` which can be used to schedule new jobs.

View file

@ -309,7 +309,7 @@ class Dispatcher(object):
which handlers were added to the group defines the priority.
Args:
handler (Handler): A Handler instance
handler (telegram.ext.Handler): A Handler instance
group (Optional[int]): The group identifier. Default is 0
"""
@ -330,7 +330,7 @@ class Dispatcher(object):
Remove a handler from the specified group
Args:
handler (Handler): A Handler instance
handler (telegram.ext.Handler): A Handler instance
group (optional[object]): The group identifier. Default is 0
"""
if handler in self.handlers[group]:

View file

@ -35,7 +35,7 @@ class Handler(object):
pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
be used to insert updates. Default is ``False``.
be used to insert updates. Default is ``False``.
pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
instance created by the ``Updater`` which can be used to schedule new jobs.
@ -85,7 +85,7 @@ class Handler(object):
Args:
update (object): The update to be handled
dispatcher (Dispatcher): The dispatcher to collect optional args
dispatcher (telegram.ext.Dispatcher): The dispatcher to collect optional args
"""
raise NotImplementedError
@ -96,7 +96,7 @@ class Handler(object):
handlers
Args:
dispatcher (Dispatcher):
dispatcher (telegram.ext.Dispatcher):
"""
optional_args = dict()

View file

@ -38,7 +38,7 @@ class InlineQueryHandler(Handler):
pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
be used to insert updates. Default is ``False``.
be used to insert updates. Default is ``False``.
pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
instance created by the ``Updater`` which can be used to schedule new jobs.

View file

@ -30,10 +30,10 @@ class JobQueue(object):
Attributes:
queue (PriorityQueue):
bot (Bot):
bot (telegram.Bot):
Args:
bot (Bot): The bot instance that should be passed to the jobs
bot (telegram.Bot): The bot instance that should be passed to the jobs
Deprecated: 5.2
prevent_autostart (Optional[bool]): Thread does not start during initialisation.
@ -60,7 +60,7 @@ class JobQueue(object):
"""Queue a new job.
Args:
job (Job): The ``Job`` instance representing the new job
job (telegram.ext.Job): The ``Job`` instance representing the new job
next_t (Optional[float]): Time in seconds in which the job should be executed first.
Defaults to ``job.interval``

View file

@ -48,7 +48,7 @@ class RegexHandler(Handler):
pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
be used to insert updates. Default is ``False``.
be used to insert updates. Default is ``False``.
pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
instance created by the ``Updater`` which can be used to schedule new jobs.

View file

@ -40,7 +40,7 @@ class StringCommandHandler(Handler):
pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
be used to insert updates. Default is ``False``.
be used to insert updates. Default is ``False``.
pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
instance created by the ``Updater`` which can be used to schedule new jobs.

View file

@ -47,7 +47,7 @@ class StringRegexHandler(Handler):
pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
be used to insert updates. Default is ``False``.
be used to insert updates. Default is ``False``.
pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
instance created by the ``Updater`` which can be used to schedule new jobs.

View file

@ -37,7 +37,7 @@ class TypeHandler(Handler):
pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
be used to insert updates. Default is ``False``.
be used to insert updates. Default is ``False``.
pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
instance created by the ``Updater`` which can be used to schedule new jobs.

View file

@ -44,7 +44,7 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
caption (Optional[str]):
reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
input_message_content (Optional[:class:`telegram.InputMessageContent`]):
**kwargs (dict): Arbitrary keyword arguments.
**kwargs (dict): Arbitrary keyword arguments.
"""

View file

@ -438,11 +438,10 @@ class Message(TelegramObject):
def forward(self, chat_id, disable_notification=False):
"""Shortcut for
bot.forwardMessage(chat_id=chat_id,
from_chat_id=update.message.chat_id,
disable_notification=disable_notification,
message_id=update.message.message_id)
>>> bot.forwardMessage(chat_id=chat_id,
... from_chat_id=update.message.chat_id,
... disable_notification=disable_notification,
... message_id=update.message.message_id)
"""
return self.bot.forwardMessage(
chat_id=chat_id,
@ -452,42 +451,48 @@ class Message(TelegramObject):
def edit_text(self, *args, **kwargs):
"""
Shortcut for ``bot.editMessageText(chat_id=message.chat_id,
message_id=message.message_id,
*args, **kwargs)``
Shortcut for
>>> bot.editMessageText(chat_id=message.chat_id,
... message_id=message.message_id,
... *args, **kwargs)
Note:
You can only edit messages that the bot sent itself,
therefore this method can only be used on the
return value of the bot.send_* family of methods.
return value of the ``bot.send_*`` family of methods.
"""
return self.bot.edit_message_text(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
def edit_caption(self, *args, **kwargs):
"""
Shortcut for ``bot.editMessageCaption(chat_id=message.chat_id,
message_id=message.message_id,
*args, **kwargs)``
Shortcut for
>>> bot.editMessageCaption(chat_id=message.chat_id,
... message_id=message.message_id,
... *args, **kwargs)
Note:
You can only edit messages that the bot sent itself,
therefore this method can only be used on the
return value of the bot.send_* family of methods.
return value of the ``bot.send_*`` family of methods.
"""
return self.bot.edit_message_caption(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
def edit_reply_markup(self, *args, **kwargs):
"""
Shortcut for ``bot.editReplyMarkup(chat_id=message.chat_id,
message_id=message.message_id,
*args, **kwargs)``
Shortcut for
>>> bot.editReplyMarkup(chat_id=message.chat_id,
... message_id=message.message_id,
... *args, **kwargs)
Note:
You can only edit messages that the bot sent itself,
therefore this method can only be used on the
return value of the bot.send_* family of methods.
return value of the ``bot.send_*`` family of methods.
"""
return self.bot.edit_message_caption(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)