conf.py (5825B)
1 # This Source Code Form is subject to the terms of the Mozilla Public 2 # License, v. 2.0. If a copy of the MPL was not distributed with this 3 # file, You can obtain one at http://mozilla.org/MPL/2.0/. 4 5 import os 6 import sys 7 8 # Set up Python environment to load build system packages. 9 OUR_DIR = os.path.dirname(__file__) 10 topsrcdir = os.path.normpath(os.path.join(OUR_DIR, "..")) 11 12 # Escapes $, [, ] and 3 dots in copy button 13 copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " 14 copybutton_prompt_is_regexp = True 15 16 EXTRA_PATHS = ( 17 "layout/tools/reftest", 18 "python/mach", 19 "python/mozbuild", 20 "python/mozversioncontrol", 21 "testing/mozbase/manifestparser", 22 "testing/mozbase/mozfile", 23 "testing/mozbase/mozprocess", 24 "testing/mozbase/moznetwork", 25 "third_party/python/jsmin", 26 "third_party/python/which", 27 "docs/_addons", 28 "taskcluster/gecko_taskgraph/test", 29 ) 30 31 sys.path[:0] = [os.path.join(topsrcdir, p) for p in EXTRA_PATHS] 32 33 sys.path.insert(0, OUR_DIR) 34 35 extensions = [ 36 "myst_parser", 37 "sphinx.ext.autodoc", 38 "sphinx.ext.autosectionlabel", 39 "sphinx.ext.doctest", 40 "sphinx.ext.graphviz", 41 "sphinx.ext.napoleon", 42 "sphinx.ext.todo", 43 "mozbuild.sphinx", 44 "sphinx_js", 45 "sphinxcontrib.jquery", 46 "sphinxcontrib.mermaid", 47 "sphinx_copybutton", 48 "sphinx_markdown_tables", 49 "sphinx_design", 50 "bzlink", 51 ] 52 53 myst_enable_extensions = [ 54 "colon_fence", 55 "smartquotes", 56 "deflist", 57 "html_admonition", 58 "fieldlist", 59 ] 60 61 # JSDoc must run successfully for dirs specified, so running 62 # tree-wide (the default) will not work currently. 63 # When adding more paths to this list, please ensure that they are not 64 # excluded from the valid-jsdoc and require-jsdoc sections in the top-level 65 # eslint-rollouts.config.mjs. 66 js_source_path = [ 67 "../browser/components/backup", 68 "../browser/components/backup/actors", 69 "../browser/components/backup/resources", 70 "../browser/components/customizableui", 71 "../browser/components/extensions", 72 "../browser/components/migration", 73 "../browser/components/migration/content", 74 "../browser/components/mozcachedohttp", 75 "../browser/components/mozcachedohttp/actors", 76 "../browser/components/uitour", 77 "../browser/components/urlbar", 78 "../browser/components/urlbar/content", 79 "../js/xpconnect/loader", 80 "../remote/marionette", 81 "../testing/mochitest/BrowserTestUtils", 82 "../testing/mochitest/tests/SimpleTest/SimpleTest.js", 83 "../testing/mochitest/tests/SimpleTest/EventUtils.js", 84 "../testing/modules/Assert.sys.mjs", 85 "../testing/modules/TestUtils.sys.mjs", 86 "../toolkit/actors", 87 "../toolkit/components/extensions", 88 "../toolkit/components/extensions/parent", 89 "../toolkit/components/ml/content/backends/ONNXPipeline.mjs", 90 "../toolkit/modules/BrowserUtils.sys.mjs", 91 "../toolkit/mozapps/extensions", 92 "../toolkit/components/prompts/src", 93 "../toolkit/components/pictureinpicture", 94 "../toolkit/components/pictureinpicture/content", 95 # This is limited to SearchService.sys.mjs for now, as we only need to 96 # generate docs for that file currently. Other search files 97 # (e.g. SearchEngineSelector) are failing due to 98 # https://github.com/pyodide/sphinx-js/issues/242 or a variant of it. 99 "../toolkit/components/search/SearchService.sys.mjs", 100 "../toolkit/components/uniffi-bindgen-gecko-js/components/generated", 101 ] 102 root_for_relative_js_paths = ".." 103 jsdoc_config_path = "jsdoc.json" 104 105 templates_path = ["_templates"] 106 source_suffix = [".rst", ".md"] 107 master_doc = "index" 108 project = "Firefox Source Docs" 109 110 # Override the search box to use Google instead of 111 # sphinx search on firefox-source-docs.mozilla.org 112 if ( 113 os.environ.get("MOZ_SOURCE_DOCS_USE_GOOGLE") == "1" 114 and os.environ.get("MOZ_SCM_LEVEL") == "3" 115 ): 116 templates_path.append("_search_template") 117 118 html_sidebars = { 119 "**": [ 120 "searchbox.html", 121 ] 122 } 123 html_logo = os.path.join( 124 topsrcdir, "browser/branding/nightly/content/firefox-wordmark.svg" 125 ) 126 html_favicon = os.path.join(topsrcdir, "browser/branding/nightly/firefox.ico") 127 128 exclude_patterns = ["_build", "_staging", "_venv", "**security/nss/legacy/**"] 129 pygments_style = "sphinx" 130 # generate label “slugs” for header anchors so that 131 # we can reference them from markdown links. 132 myst_heading_anchors = 5 133 134 # We need to perform some adjustment of the settings and environment 135 # when running on Read The Docs. 136 on_rtd = os.environ.get("READTHEDOCS", None) == "True" 137 138 if on_rtd: 139 # SHELL isn't set on RTD and mach.mixin.process's import raises if a 140 # shell-related environment variable can't be found. Set the variable here 141 # to hack us into working on RTD. 142 assert "SHELL" not in os.environ 143 os.environ["SHELL"] = "/bin/bash" 144 else: 145 # We only need to set the RTD theme when not on RTD because the RTD 146 # environment handles this otherwise. 147 148 html_theme = "sphinx_rtd_theme" 149 150 # As we parse the error messages and they can be translated, force 151 # the english locale 152 os.environ["LANG"] = "C" 153 154 html_static_path = ["_static"] 155 htmlhelp_basename = "FirefoxTreeDocs" 156 157 moz_project_name = "main" 158 159 html_show_copyright = False 160 161 # Only run autosection for the page title. 162 # Otherwise, we have a huge number of duplicate links. 163 # For example, the page https://firefox-source-docs.mozilla.org/code-quality/lint/ 164 # is called "Linting" 165 # just like https://firefox-source-docs.mozilla.org/remote/CodeStyle.html 166 autosectionlabel_maxdepth = 1 167 168 169 def install_sphinx_design(app, pagename, templatename, context, doctree): 170 if "perfdocs" in pagename: 171 app.add_js_file("sphinx_design.js") 172 app.add_css_file("sphinx_design.css") 173 174 175 def setup(app): 176 app.add_css_file("custom_theme.css") 177 app.connect("html-page-context", install_sphinx_design)