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 from __future__ import absolute_import, unicode_literals
   6
   7 import os
   8 import sys
   9
  10 from recommonmark.transform import AutoStructify
  11
  12 # Set up Python environment to load build system packages.
  13 OUR_DIR = os.path.dirname(__file__)
  14 topsrcdir = os.path.normpath(os.path.join(OUR_DIR, ".."))
  15
  16 copybutton_prompt_text = ">>> |\\\\$ |\\[\\d*\\]: |\\.\\.\\.: "
  17 copybutton_prompt_is_regexp = True
  18
  19 EXTRA_PATHS = (
  20     "layout/tools/reftest",
  21     "python/mach",
  22     "python/mozbuild",
  23     "python/mozversioncontrol",
  24     "testing/mozbase/manifestparser",
  25     "testing/mozbase/mozfile",
  26     "testing/mozbase/mozprocess",
  27     "third_party/python/futures",
  28     "third_party/python/jsmin",
  29     "third_party/python/which",
  30 )
  31
  32 sys.path[:0] = [os.path.join(topsrcdir, p) for p in EXTRA_PATHS]
  33
  34 sys.path.insert(0, OUR_DIR)
  35
  36 extensions = [
  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.mermaid",
  46     "recommonmark",
  47     "sphinx_copybutton",
  48 ]
  49
  50 # JSDoc must run successfully for dirs specified, so running
  51 # tree-wide (the default) will not work currently.
  52 js_source_path = [
  53     "browser/components/extensions",
  54     "browser/components/uitour",
  55     "testing/marionette",
  56     "toolkit/components/extensions",
  57     "toolkit/components/extensions/parent",
  58     "toolkit/components/featuregates",
  59     "toolkit/mozapps/extensions",
  60     "toolkit/components/prompts/src",
  61 ]
  62 root_for_relative_js_paths = "."
  63 jsdoc_config_path = "jsdoc.json"
  64
  65 templates_path = ["_templates"]
  66 source_suffix = [".rst", ".md"]
  67 master_doc = "index"
  68 project = "Firefox Source Docs"
  69 html_logo = os.path.join(topsrcdir, "browser/branding/nightly/content/firefox-wordmark.svg")
  70 html_favicon = os.path.join(topsrcdir, "browser/branding/nightly/firefox.ico")
  71
  72 exclude_patterns = ["_build", "_staging", "_venv"]
  73 pygments_style = "sphinx"
  74
  75 # We need to perform some adjustment of the settings and environment
  76 # when running on Read The Docs.
  77 on_rtd = os.environ.get("READTHEDOCS", None) == "True"
  78
  79 if on_rtd:
  80     # SHELL isn't set on RTD and mach.mixin.process's import raises if a
  81     # shell-related environment variable can't be found. Set the variable here
  82     # to hack us into working on RTD.
  83     assert "SHELL" not in os.environ
  84     os.environ["SHELL"] = "/bin/bash"
  85 else:
  86     # We only need to set the RTD theme when not on RTD because the RTD
  87     # environment handles this otherwise.
  88     import sphinx_rtd_theme
  89
  90     html_theme = "sphinx_rtd_theme"
  91     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
  92
  93
  94 html_static_path = ["_static"]
  95 htmlhelp_basename = "MozillaTreeDocs"
  96
  97 moz_project_name = "main"
  98
  99 html_show_copyright = False
 100
 101
 102 def setup(app):
 103     app.add_config_value(
 104         "recommonmark_config",
 105         {
 106             # Crashes with sphinx
 107             "enable_inline_math": False,
 108             # We use it for testing/web-platform/tests
 109             "enable_eval_rst": True,
 110         },
 111         True,
 112     )
 113     app.add_stylesheet("custom_theme.css")
 114     app.add_transform(AutoStructify)