docs/conf.py

   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 # JSDoc must run successfully for dirs specified, so running
  54 # tree-wide (the default) will not work currently.
  55 # When adding more paths to this list, please ensure that they are not
  56 # excluded from valid-jsdoc in the top-level .eslintrc.js.
  57 js_source_path = [
  58     "../browser/components/backup",
  59     "../browser/components/backup/resources",
  60     "../browser/components/extensions",
  61     "../browser/components/migration",
  62     "../browser/components/migration/content",
  63     "../browser/components/uitour",
  64     "../browser/components/urlbar",
  65     "../remote/marionette",
  66     "../testing/mochitest/BrowserTestUtils",
  67     "../testing/mochitest/tests/SimpleTest/SimpleTest.js",
  68     "../testing/mochitest/tests/SimpleTest/EventUtils.js",
  69     "../testing/modules/Assert.sys.mjs",
  70     "../testing/modules/TestUtils.sys.mjs",
  71     "../toolkit/actors",
  72     "../toolkit/components/extensions",
  73     "../toolkit/components/extensions/parent",
  74     "../toolkit/components/featuregates",
  75     "../toolkit/mozapps/extensions",
  76     "../toolkit/components/prompts/src",
  77     "../toolkit/components/pictureinpicture",
  78     "../toolkit/components/pictureinpicture/content",
  79     "../toolkit/components/search",
  80 ]
  81 root_for_relative_js_paths = ".."
  82 jsdoc_config_path = "jsdoc.json"
  83
  84 templates_path = ["_templates"]
  85 source_suffix = [".rst", ".md"]
  86 master_doc = "index"
  87 project = "Firefox Source Docs"
  88
  89 # Override the search box to use Google instead of
  90 # sphinx search on firefox-source-docs.mozilla.org
  91 if (
  92     os.environ.get("MOZ_SOURCE_DOCS_USE_GOOGLE") == "1"
  93     and os.environ.get("MOZ_SCM_LEVEL") == "3"
  94 ):
  95     templates_path.append("_search_template")
  96
  97 html_sidebars = {
  98     "**": [
  99         "searchbox.html",
 100     ]
 101 }
 102 html_logo = os.path.join(
 103     topsrcdir, "browser/branding/nightly/content/firefox-wordmark.svg"
 104 )
 105 html_favicon = os.path.join(topsrcdir, "browser/branding/nightly/firefox.ico")
 106
 107 exclude_patterns = ["_build", "_staging", "_venv", "**security/nss/legacy/**"]
 108 pygments_style = "sphinx"
 109 # generate label “slugs” for header anchors so that
 110 # we can reference them from markdown links.
 111 myst_heading_anchors = 5
 112
 113 # We need to perform some adjustment of the settings and environment
 114 # when running on Read The Docs.
 115 on_rtd = os.environ.get("READTHEDOCS", None) == "True"
 116
 117 if on_rtd:
 118     # SHELL isn't set on RTD and mach.mixin.process's import raises if a
 119     # shell-related environment variable can't be found. Set the variable here
 120     # to hack us into working on RTD.
 121     assert "SHELL" not in os.environ
 122     os.environ["SHELL"] = "/bin/bash"
 123 else:
 124     # We only need to set the RTD theme when not on RTD because the RTD
 125     # environment handles this otherwise.
 126     import sphinx_rtd_theme
 127
 128     html_theme = "sphinx_rtd_theme"
 129     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 130
 131
 132 html_static_path = ["_static"]
 133 htmlhelp_basename = "FirefoxTreeDocs"
 134
 135 moz_project_name = "main"
 136
 137 html_show_copyright = False
 138
 139 # Only run autosection for the page title.
 140 # Otherwise, we have a huge number of duplicate links.
 141 # For example, the page https://firefox-source-docs.mozilla.org/code-quality/lint/
 142 # is called "Linting"
 143 # just like https://firefox-source-docs.mozilla.org/remote/CodeStyle.html
 144 autosectionlabel_maxdepth = 1
 145
 146
 147 def install_sphinx_design(app, pagename, templatename, context, doctree):
 148     if "perfdocs" in pagename:
 149         app.add_js_file("sphinx_design.js")
 150         app.add_css_file("sphinx_design.css")
 151
 152
 153 def setup(app):
 154     app.add_css_file("custom_theme.css")
 155     app.connect("html-page-context", install_sphinx_design)