import os import re import sys from pathlib import Path # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. from sphinx.application import Sphinx sys.path.insert(0, os.path.abspath("../..")) # -- General configuration ------------------------------------------------ # General information about the project. project = "python-telegram-bot" copyright = "2015-2023, Leandro Toledo" author = "Leandro Toledo" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. version = "20.7" # telegram.__version__[:3] # The full version, including alpha/beta/rc tags. release = "20.7" # telegram.__version__ # If your documentation needs a minimal Sphinx version, state it here. needs_sphinx = "6.1.3" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.intersphinx", "sphinx.ext.linkcode", "sphinx.ext.extlinks", "sphinx_paramlinks", "sphinx_copybutton", "sphinx_inline_tabs", "sphinxcontrib.mermaid", "sphinx_search.extension", ] # For shorter links to Wiki in docstrings extlinks = { "wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s"), "pr": ("https://github.com/python-telegram-bot/python-telegram-bot/pull/%s", "#%s"), "issue": ("https://github.com/python-telegram-bot/python-telegram-bot/issues/%s", "#%s"), } # Use intersphinx to reference the python builtin library docs intersphinx_mapping = { "python": ("https://docs.python.org/3", None), "APScheduler": ("https://apscheduler.readthedocs.io/en/3.x/", None), } # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: source_suffix = ".rst" # The master toctree document. master_doc = "index" # Global substitutions rst_prolog = (Path.cwd() / "../substitutions/global.rst").read_text(encoding="utf-8") # -- Extension settings ------------------------------------------------ napoleon_use_admonition_for_examples = True # Don't show type hints in the signature - that just makes it hardly readable # and we document the types anyway autodoc_typehints = "none" # Show docstring for special members autodoc_default_options = { "special-members": True, # For some reason, __weakref__ can not be ignored by using "inherited-members" in all cases # so we list it here. "exclude-members": "__init__, __weakref__", } # Fail on warnings & unresolved references etc nitpicky = True # Paramlink style paramlinks_hyperlink_param = "name" # Linkcheck settings linkcheck_ignore = [ # Let's not check issue/PR links - that's wasted resources r"http(s)://github\.com/python-telegram-bot/python-telegram-bot/(issues|pull)/\d+/?", # For some reason linkcheck has a problem with these two: re.escape("https://github.com/python-telegram-bot/python-telegram-bot/discussions/new"), re.escape("https://github.com/python-telegram-bot/python-telegram-bot/issues/new"), # Anchors are apparently inserted by GitHub dynamically, so let's skip checking them "https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples#", r"https://github\.com/python-telegram-bot/python-telegram-bot/wiki/[\w\-_,]+\#", ] linkcheck_allowed_redirects = { # Redirects to the default version are okay r"https://docs\.python-telegram-bot\.org/.*": ( r"https://docs\.python-telegram-bot\.org/en/[\w\d\.]+/.*" ), # pre-commit.ci always redirects to the latest run re.escape( "https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master" ): r"https://results\.pre-commit\.ci/run/github/.*", } # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" # Decides the language used for syntax highlighting of code blocks. highlight_language = "python3" # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = "furo" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the documentation. html_theme_options = { "navigation_with_keys": True, "dark_css_variables": { "admonition-title-font-size": "0.95rem", "admonition-font-size": "0.92rem", }, "light_css_variables": { "admonition-title-font-size": "0.95rem", "admonition-font-size": "0.92rem", }, "announcement": ( "PTB has undergone significant changes in v20. Please read the documentation " "carefully and also check out the transition guide in the " 'wiki.' ), "footer_icons": [ { # Telegram channel logo "name": "Telegram Channel", "url": "https://t.me/pythontelegrambotchannel/", # Following svg is from https://react-icons.github.io/react-icons/search?q=telegram "html": ( '' '' ), "class": "", }, { # Github logo "name": "GitHub", "url": "https://github.com/python-telegram-bot/python-telegram-bot/", "html": ( '' "" ), "class": "", }, { # PTB website logo - globe "name": "python-telegram-bot website", "url": "https://python-telegram-bot.org/", "html": ( '' '' ), "class": "", }, ], } # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". html_title = f"python-telegram-bot
v{version}" # The name of an image file (relative to this directory) to place at the top # of the sidebar. html_logo = "ptb-logo_1024.png" # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. html_favicon = "ptb-logo_1024.ico" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] html_css_files = [ "style_external_link.css", "style_mermaid_diagrams.css", "style_sidebar_brand.css", "style_general.css", "style_admonitions.css", "style_images.css", ] html_permalinks_icon = "ΒΆ" # Furo's default permalink icon is `#` which doesn't look great imo. # Output file base name for HTML help builder. htmlhelp_basename = "python-telegram-bot-doc" # The base URL which points to the root of the HTML documentation. It is used to indicate the # location of document using The Canonical Link Relation. Default: ''. html_baseurl = "https://docs.python-telegram-bot.org" # -- Options for LaTeX output --------------------------------------------- latex_elements = { # The paper size ('letterpaper' or 'a4paper'). "papersize": "a4paper", # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. "preamble": r"""\setcounter{tocdepth}{2} \usepackage{enumitem} \setlistdepth{99}""", # Latex figure (float) alignment #'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, "python-telegram-bot.tex", "python-telegram-bot Documentation", author, "manual"), ] # The name of an image file (relative to this directory) to place at the top of # the title page. latex_logo = "ptb-logo_1024.png" # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [(master_doc, "python-telegram-bot", "python-telegram-bot Documentation", [author], 1)] # rtd_sphinx_search_file_type = "un-minified" # Configuration for furo-sphinx-search # -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ ( master_doc, "python-telegram-bot", "python-telegram-bot Documentation", author, "python-telegram-bot", "We have made you a wrapper you can't refuse", "Miscellaneous", ), ] # -- script stuff -------------------------------------------------------- # Due to Sphinx behaviour, these imports only work when imported here, not at top of module. # Not used but must be imported for the linkcode extension to find it from docs.auxil.link_code import linkcode_resolve from docs.auxil.sphinx_hooks import ( autodoc_process_bases, autodoc_process_docstring, autodoc_skip_member, ) from docs.auxil.tg_const_role import CONSTANTS_ROLE, TGConstXRefRole def setup(app: Sphinx): app.connect("autodoc-skip-member", autodoc_skip_member) app.connect("autodoc-process-bases", autodoc_process_bases) # The default priority is 500. We want our function to run before napoleon doc-conversion # and sphinx-paramlinks do, b/c otherwise the inserted kwargs in the bot methods won't show # up in the objects.inv file that Sphinx generates (i.e. not in the search). app.connect("autodoc-process-docstring", autodoc_process_docstring, priority=100) app.add_role_to_domain("py", CONSTANTS_ROLE, TGConstXRefRole())