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 re
   9 import sys
  10
  11 from datetime import datetime
  12
  13 from recommonmark.transform import AutoStructify
  14
  15 # Set up Python environment to load build system packages.
  16 OUR_DIR = os.path.dirname(__file__)
  17 topsrcdir = os.path.normpath(os.path.join(OUR_DIR, '..'))
  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 ]
  48
  49 # JSDoc must run successfully for dirs specified, so running
  50 # tree-wide (the default) will not work currently.
  51 js_source_path = [
  52     'browser/components/extensions',
  53     'browser/components/uitour',
  54     'testing/marionette',
  55     'toolkit/components/extensions',
  56     'toolkit/components/extensions/parent',
  57     'toolkit/components/featuregates',
  58     'toolkit/mozapps/extensions',
  59     'toolkit/components/prompts/src',
  60 ]
  61 root_for_relative_js_paths = '.'
  62 jsdoc_config_path = 'jsdoc.json'
  63
  64 templates_path = ['_templates']
  65 source_suffix = '.rst'
  66 source_suffix = ['.rst', '.md']
  67 master_doc = 'index'
  68 project = u'Firefox Source Tree Docs'
  69 year = datetime.now().year
  70
  71 # Grab the version from the source tree's milestone.
  72 # FUTURE Use Python API from bug 941299.
  73 with open(os.path.join(topsrcdir, 'config', 'milestone.txt'), 'rt') as fh:
  74     for line in fh:
  75         line = line.strip()
  76
  77         if not line or line.startswith('#'):
  78             continue
  79
  80         release = line
  81         break
  82
  83 version = re.sub(r'[ab]\d+$', '', release)
  84
  85 exclude_patterns = ['_build', '_staging', '_venv']
  86 pygments_style = 'sphinx'
  87
  88 # We need to perform some adjustment of the settings and environment
  89 # when running on Read The Docs.
  90 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
  91
  92 if on_rtd:
  93     # SHELL isn't set on RTD and mach.mixin.process's import raises if a
  94     # shell-related environment variable can't be found. Set the variable here
  95     # to hack us into working on RTD.
  96     assert 'SHELL' not in os.environ
  97     os.environ['SHELL'] = '/bin/bash'
  98 else:
  99     # We only need to set the RTD theme when not on RTD because the RTD
 100     # environment handles this otherwise.
 101     import sphinx_rtd_theme
 102     html_theme = 'sphinx_rtd_theme'
 103     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 104
 105
 106 html_static_path = ['_static']
 107 htmlhelp_basename = 'MozillaTreeDocs'
 108
 109 moz_project_name = 'main'
 110
 111 html_show_copyright = False
 112
 113
 114 def setup(app):
 115     app.add_config_value('recommonmark_config', {
 116         # Crashes with sphinx
 117         'enable_inline_math': False,
 118         # We use it for testing/web-platform/tests
 119         'enable_eval_rst': True,
 120             }, True)
 121     app.add_stylesheet('custom_theme.css')
 122     app.add_transform(AutoStructify)