conf.py (6158B)
1 # Configuration file for the Sphinx documentation builder. 2 # 3 # This file only contains a selection of the most common options. For a full 4 # list see the documentation: 5 # https://www.sphinx-doc.org/en/master/usage/configuration.html 6 7 import datetime 8 import importlib 9 import inspect 10 import os 11 import subprocess 12 import sys 13 14 # -- Path setup -------------------------------------------------------------- 15 16 # If extensions (or modules to document with autodoc) are in another directory, 17 # add these directories to sys.path here. If the directory is relative to the 18 # documentation root, use os.path.abspath to make it absolute, like shown here. 19 sys.path.insert(0, os.path.join(os.path.abspath(".."), "src")) 20 21 22 # -- Project information ----------------------------------------------------- 23 24 project = "websockets" 25 copyright = f"2013-{datetime.date.today().year}, Aymeric Augustin and contributors" 26 author = "Aymeric Augustin" 27 28 from websockets.version import tag as version, version as release 29 30 31 # -- General configuration --------------------------------------------------- 32 33 nitpicky = True 34 35 nitpick_ignore = [ 36 # topics/design.rst discusses undocumented APIs 37 ("py:meth", "client.WebSocketClientProtocol.handshake"), 38 ("py:meth", "server.WebSocketServerProtocol.handshake"), 39 ("py:attr", "legacy.protocol.WebSocketCommonProtocol.is_client"), 40 ("py:attr", "legacy.protocol.WebSocketCommonProtocol.messages"), 41 ("py:meth", "legacy.protocol.WebSocketCommonProtocol.close_connection"), 42 ("py:attr", "legacy.protocol.WebSocketCommonProtocol.close_connection_task"), 43 ("py:meth", "legacy.protocol.WebSocketCommonProtocol.keepalive_ping"), 44 ("py:attr", "legacy.protocol.WebSocketCommonProtocol.keepalive_ping_task"), 45 ("py:meth", "legacy.protocol.WebSocketCommonProtocol.transfer_data"), 46 ("py:attr", "legacy.protocol.WebSocketCommonProtocol.transfer_data_task"), 47 ("py:meth", "legacy.protocol.WebSocketCommonProtocol.connection_open"), 48 ("py:meth", "legacy.protocol.WebSocketCommonProtocol.ensure_open"), 49 ("py:meth", "legacy.protocol.WebSocketCommonProtocol.fail_connection"), 50 ("py:meth", "legacy.protocol.WebSocketCommonProtocol.connection_lost"), 51 ("py:meth", "legacy.protocol.WebSocketCommonProtocol.read_message"), 52 ("py:meth", "legacy.protocol.WebSocketCommonProtocol.write_frame"), 53 ] 54 55 # Add any Sphinx extension module names here, as strings. They can be 56 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 57 # ones. 58 extensions = [ 59 "sphinx.ext.autodoc", 60 "sphinx.ext.intersphinx", 61 "sphinx.ext.linkcode", 62 "sphinx.ext.napoleon", 63 "sphinx_copybutton", 64 "sphinx_inline_tabs", 65 "sphinxcontrib.spelling", 66 "sphinxcontrib_trio", 67 "sphinxext.opengraph", 68 ] 69 # It is currently inconvenient to install PyEnchant on Apple Silicon. 70 try: 71 import sphinxcontrib.spelling 72 except ImportError: 73 extensions.remove("sphinxcontrib.spelling") 74 75 autodoc_typehints = "description" 76 77 autodoc_typehints_description_target = "documented" 78 79 # Workaround for https://github.com/sphinx-doc/sphinx/issues/9560 80 from sphinx.domains.python import PythonDomain 81 82 assert PythonDomain.object_types["data"].roles == ("data", "obj") 83 PythonDomain.object_types["data"].roles = ("data", "class", "obj") 84 85 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} 86 87 spelling_show_suggestions = True 88 89 # Add any paths that contain templates here, relative to this directory. 90 templates_path = ["_templates"] 91 92 # List of patterns, relative to source directory, that match files and 93 # directories to ignore when looking for source files. 94 # This pattern also affects html_static_path and html_extra_path. 95 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] 96 97 # Configure viewcode extension. 98 from websockets.version import commit 99 100 code_url = f"https://github.com/python-websockets/websockets/blob/{commit}" 101 102 def linkcode_resolve(domain, info): 103 # Non-linkable objects from the starter kit in the tutorial. 104 if domain == "js" or info["module"] == "connect4": 105 return 106 107 assert domain == "py", "expected only Python objects" 108 109 mod = importlib.import_module(info["module"]) 110 if "." in info["fullname"]: 111 objname, attrname = info["fullname"].split(".") 112 obj = getattr(mod, objname) 113 try: 114 # object is a method of a class 115 obj = getattr(obj, attrname) 116 except AttributeError: 117 # object is an attribute of a class 118 return None 119 else: 120 obj = getattr(mod, info["fullname"]) 121 122 try: 123 file = inspect.getsourcefile(obj) 124 lines = inspect.getsourcelines(obj) 125 except TypeError: 126 # e.g. object is a typing.Union 127 return None 128 file = os.path.relpath(file, os.path.abspath("..")) 129 if not file.startswith("src/websockets"): 130 # e.g. object is a typing.NewType 131 return None 132 start, end = lines[1], lines[1] + len(lines[0]) - 1 133 134 return f"{code_url}/{file}#L{start}-L{end}" 135 136 # Configure opengraph extension 137 138 # Social cards don't support the SVG logo. Also, the text preview looks bad. 139 ogp_social_cards = {"enable": False} 140 141 142 # -- Options for HTML output ------------------------------------------------- 143 144 # The theme to use for HTML and HTML Help pages. See the documentation for 145 # a list of builtin themes. 146 html_theme = "furo" 147 148 html_theme_options = { 149 "light_css_variables": { 150 "color-brand-primary": "#306998", # blue from logo 151 "color-brand-content": "#0b487a", # blue more saturated and less dark 152 }, 153 "dark_css_variables": { 154 "color-brand-primary": "#ffd43bcc", # yellow from logo, more muted than content 155 "color-brand-content": "#ffd43bd9", # yellow from logo, transparent like text 156 }, 157 "sidebar_hide_name": True, 158 } 159 160 html_logo = "_static/websockets.svg" 161 162 html_favicon = "_static/favicon.ico" 163 164 # Add any paths that contain custom static files (such as style sheets) here, 165 # relative to this directory. They are copied after the builtin static files, 166 # so a file named "default.css" will overwrite the builtin "default.css". 167 html_static_path = ["_static"] 168 169 html_copy_source = False 170 171 html_show_sphinx = False