Title: HTML tags. html_short_title = f'{release} documentation' # Deployment preview information # (See .readthedocs.yml and https://docs.readthedocs.io/en/stable/reference/environment-variables.html) is_deployment_preview = os.getenv("READTHEDOCS_VERSION_TYPE") == "external" repository_url = os.getenv("READTHEDOCS_GIT_CLONE_URL", "") repository_url = repository_url.removesuffix(".git") html_context = { "is_deployment_preview": is_deployment_preview, "repository_url": repository_url or None, "pr_id": os.getenv("READTHEDOCS_VERSION"), "enable_analytics": os.getenv("PYTHON_DOCS_ENABLE_ANALYTICS"), "source_branch": branch, } # This 'Last updated on:' timestamp is inserted at the bottom of every page. html_last_updated_fmt = '%b %d, %Y (%H:%M UTC)' html_last_updated_use_utc = True # Path to find HTML templates to override theme templates_path = ['tools/templates'] # We link to sources on GitHub, so don't copy them into the HTML output. html_copy_source = False # Custom sidebar templates, filenames relative to this file. html_sidebars = { # Defaults taken from https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars # Removes the quick search block '**': ['localtoc.html', 'relations.html', 'customsourcelink.html'], 'index': ['indexsidebar.html'], } # Additional templates that should be rendered to pages. html_additional_pages = { 'download': 'download.html', 'index': 'indexcontent.html', } # Output an OpenSearch description file. html_use_opensearch = 'https://docs.python.org/' + version # Additional static files. html_static_path = ['_static', 'tools/static'] # Output file base name for HTML help builder. htmlhelp_basename = 'python' + release.replace('.', '') # Split the index html_split_index = True # Split pot files one per reST file gettext_compact = False # Options for LaTeX output # ------------------------ latex_engine = 'xelatex' latex_elements = { # For the LaTeX preamble. 'preamble': r''' \authoraddress{ \sphinxstrong{Python Software Foundation}\\ Email: \sphinxemail{docs@python.org} } \let\Verbatim=\OriginalVerbatim \let\endVerbatim=\endOriginalVerbatim \setcounter{tocdepth}{2} ''', # The paper size ('letterpaper' or 'a4paper'). 'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). 'pointsize': '10pt', 'maxlistdepth': '8', # See https://github.com/python/cpython/issues/139588 } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ ( 'c-api/index', 'c-api.tex', 'The Python/C API', _doc_authors, 'manual', ), ( 'extending/index', 'extending.tex', 'Extending and Embedding Python', _doc_authors, 'manual', ), ( 'installing/index', 'installing.tex', 'Installing Python Modules', _doc_authors, 'manual', ), ( 'builtins/index', 'builtins.tex', 'Python Built-ins Reference', _doc_authors, 'manual', ), ( 'library/index', 'library.tex', 'The Python Library Reference', _doc_authors, 'manual', ), ( 'reference/index', 'reference.tex', 'The Python Language Reference', _doc_authors, 'manual', ), ( 'tutorial/index', 'tutorial.tex', 'Python Tutorial', _doc_authors, 'manual', ), ( 'using/index', 'using.tex', 'Python Setup and Usage', _doc_authors, 'manual', ), ( 'faq/index', 'faq.tex', 'Python Frequently Asked Questions', _doc_authors, 'manual', ), ( 'whatsnew/' + version, 'whatsnew.tex', 'What\'s New in Python', _doc_authors, 'howto', ), ] # Collect all HOWTOs individually latex_documents.extend( ( 'howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex', '', _doc_authors, 'howto', ) for fn in os.listdir('howto') if fn.endswith('.rst') and fn != 'index.rst' ) # Documents to append as an appendix to all manuals. latex_appendices = ['glossary', 'about', 'license', 'copyright'] # Options for Epub output # ----------------------- epub_author = _doc_authors epub_publisher = 'Python Software Foundation' epub_exclude_files = ('index.xhtml', 'download.xhtml') # index pages are not valid xhtml # https://github.com/sphinx-doc/sphinx/issues/12359 epub_use_index = False # The default depth of 3 lists over a thousand entries, which makes the # table of contents hard to navigate in e-book readers epub_tocdepth = 2 # translation tag # --------------- language_code = None for arg in sys.argv: if arg.startswith('language='): language_code = arg.split('=', 1)[1] if language_code: tags.add('translation') # noqa: F821 rst_epilog += f"""\ .. _TRANSLATION_REPO: https://github.com/python/python-docs-{language_code.replace("_", "-").lower()} """ # noqa: F821 else: rst_epilog += """\ .. _TRANSLATION_REPO: https://github.com/python """ # Options for the coverage checker # -------------------------------- # The coverage checker will ignore all modules/functions/classes whose names # match any of the following regexes (using re.match). coverage_ignore_modules = [ r'[T|t][k|K]', ] coverage_ignore_functions = [ 'test($|_)', ] coverage_ignore_classes = [] # Glob patterns for C source files for C API coverage, relative to this directory. coverage_c_path = [ '../Include/*.h', ] # Regexes to find C items in the source files. coverage_c_regexes = { 'cfunction': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)', 'data': r'^PyAPI_DATA\(.*\)\s+([^_][\w_]+)', 'macro': r'^#define ([^_][\w_]+)\(.*\)[\s|\\]', } # The coverage checker will ignore all C items whose names match these regexes # (using re.match) -- the keys must be the same as in coverage_c_regexes. coverage_ignore_c_items = { # 'cfunction': [...] } # Options for the link checker # ---------------------------- linkcheck_allowed_redirects = { # bpo-NNNN -> BPO -> GH Issues r'https://bugs.python.org/issue\?@action=redirect&bpo=\d+': r'https://github.com/python/cpython/issues/\d+', # GH-NNNN used to refer to pull requests r'https://github.com/python/cpython/issues/\d+': r'https://github.com/python/cpython/pull/\d+', # :source:`something` linking files in the repository r'https://github.com/python/cpython/tree/.*': 'https://github.com/python/cpython/blob/.*', # Intentional HTTP use at Misc/NEWS.d/3.5.0a1.rst r'http://www.python.org/$': 'https://www.python.org/$', # Microsoft's redirects to learn.microsoft.com r'https://msdn.microsoft.com/.*': 'https://learn.microsoft.com/.*', r'https://docs.microsoft.com/.*': 'https://learn.microsoft.com/.*', r'https://go.microsoft.com/fwlink/\?LinkID=\d+': 'https://learn.microsoft.com/.*', # Debian's man page redirects to its current stable version r'https://manpages.debian.org/\w+\(\d(\w+)?\)': r'https://manpages.debian.org/\w+/[\w/\-\.]*\.\d(\w+)?\.en\.html', # Language redirects r'https://toml.io': 'https://toml.io/en/', r'https://www.redhat.com': 'https://www.redhat.com/en', # pypi.org project name normalization (upper to lowercase, underscore to hyphen) r'https://pypi.org/project/[A-Za-z\d_\-\.]+/': r'https://pypi.org/project/[a-z\d\-\.]+/', # Discourse title name expansion (text changes when title is edited) r'https://discuss\.python\.org/t/\d+': r'https://discuss\.python\.org/t/.*/\d+', # Other redirects r'https://www.boost.org/libs/.+': r'https://www.boost.org/doc/libs/\d_\d+_\d/.+', r'https://support.microsoft.com/en-us/help/\d+': 'https://support.microsoft.com/en-us/topic/.+', r'https://perf.wiki.kernel.org$': 'https://perf.wiki.kernel.org/index.php/Main_Page', r'https://www.sqlite.org': 'https://www.sqlite.org/index.html', r'https://mitpress.mit.edu/sicp$': 'https://mitpress.mit.edu/9780262510875/structure-and-interpretation-of-computer-programs/', r'https://www.python.org/psf/': 'https://www.python.org/psf-landing/', } linkcheck_anchors_ignore = [ # ignore anchors that start with a '/', e.g. Wikipedia media files: # https://en.wikipedia.org/wiki/Walrus#/media/File:Pacific_Walrus_-_Bull_(8247646168).jpg r'\/.*', ] linkcheck_ignore = [ # The crawler gets "Anchor not found" r'https://developer.apple.com/documentation/.+?#.*', r'https://devguide.python.org.+?/#.*', r'https://github.com.+?#.*', # Robot crawlers not allowed: "403 Client Error: Forbidden" r'https://support.enthought.com/hc/.*', # SSLError CertificateError, even though it is valid r'https://unix.org/version2/whatsnew/lp64_wp.html', ] # Options to adjust search results sorting # ---------------------------------------- html_search_scorer = "tools/static/search_scorer.js" # Options for sphinx.ext.extlinks # ------------------------------- # This config is a dictionary of external sites, # mapping unique short aliases to a base URL and a prefix. # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html extlinks = { "oss-fuzz": ("https://issues.oss-fuzz.com/issues/%s", "#%s"), "pypi": ("https://pypi.org/project/%s/", "%s"), "source": (f"https://github.com/python/cpython/tree/{branch}/%s", "%s"), } extlinks_detect_hardcoded_links = True # Options for c_annotations extension # ----------------------------------- # Relative filename of the data files refcount_file = 'data/refcounts.dat' stable_abi_file = 'data/stable_abi.dat' threadsafety_file = 'data/threadsafety.dat' # Options for notfound.extension # ------------------------------- if not os.getenv("READTHEDOCS"): if language_code: notfound_urls_prefix = ( f'/{language_code.replace("_", "-").lower()}/{version}/' ) else: notfound_urls_prefix = f'/{version}/' # Options for sphinxext-opengraph # ------------------------------- ogp_canonical_url = 'https://docs.python.org/3/' ogp_site_name = 'Python documentation' ogp_social_cards = { # Used when matplotlib is installed 'image': '_static/og-image.png', 'line_color': '#3776ab', } ogp_custom_meta_tags = ('',) if 'create-social-cards' not in tags: # noqa: F821 # Define a static preview image when not creating social cards ogp_image = '_static/og-image.png' ogp_custom_meta_tags += ( '', '', ) # Options for sphinxext-rediraffe # ------------------------------- rediraffe_redirects = { # Splitting builtins from library "library/functions.rst": "builtins/functions.rst", "library/stdtypes.rst": "builtins/stdtypes.rst", "library/constants.rst": "builtins/constants.rst", "library/exceptions.rst": "builtins/exceptions.rst", "library/threadsafety.rst": "builtins/threadsafety.rst", "library/time-complexity.rst": "builtins/time-complexity.rst", } # Refuse to run the doctest builder under a mismatched Python # ----------------------------------------------------------- def _check_doctest_interpreter(app): # The doctests are executed by the interpreter running Sphinx, # so refuse to run them if its version doesn't match the source tree. if app.builder.name != "doctest": return running_version = f"{sys.version_info.major}.{sys.version_info.minor}" if running_version != version: from sphinx.util import logging as sphinx_logging logger = sphinx_logging.getLogger(__name__) logger.error( "The doctests are executed by the Python running Sphinx, " "which is Python %s, however this source tree is Python %s, " "so they would test Python %s rather than the code " "documented here.\n" "Recreate the venv with a matching interpreter, for example: " "'make clean-venv && make venv PYTHON=../python'.", running_version, version, running_version, ) raise SystemExit(1) def setup(app): app.connect("builder-inited", _check_doctest_interpreter) return { "version": "1.0", "parallel_read_safe": True, "parallel_write_safe": True, }
Domain: github.com
Links:
| Read the Docs | https://about.readthedocs.com/ |