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 ]
  60 root_for_relative_js_paths = '.'
  61 jsdoc_config_path = 'jsdoc.json'
  62
  63 templates_path = ['_templates']
  64 source_suffix = '.rst'
  65 source_suffix = ['.rst', '.md']
  66 master_doc = 'index'
  67 project = u'Mozilla Source Tree Docs'
  68 year = datetime.now().year
  69
  70 # Grab the version from the source tree's milestone.
  71 # FUTURE Use Python API from bug 941299.
  72 with open(os.path.join(topsrcdir, 'config', 'milestone.txt'), 'rt') as fh:
  73     for line in fh:
  74         line = line.strip()
  75
  76         if not line or line.startswith('#'):
  77             continue
  78
  79         release = line
  80         break
  81
  82 version = re.sub(r'[ab]\d+$', '', release)
  83
  84 exclude_patterns = ['_build', '_staging', '_venv']
  85 pygments_style = 'sphinx'
  86
  87 # We need to perform some adjustment of the settings and environment
  88 # when running on Read The Docs.
  89 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
  90
  91 if on_rtd:
  92     # SHELL isn't set on RTD and mach.mixin.process's import raises if a
  93     # shell-related environment variable can't be found. Set the variable here
  94     # to hack us into working on RTD.
  95     assert 'SHELL' not in os.environ
  96     os.environ['SHELL'] = '/bin/bash'
  97 else:
  98     # We only need to set the RTD theme when not on RTD because the RTD
  99     # environment handles this otherwise.
 100     import sphinx_rtd_theme
 101     html_theme = 'sphinx_rtd_theme'
 102     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 103
 104
 105 html_static_path = ['_static']
 106 htmlhelp_basename = 'MozillaTreeDocs'
 107
 108 moz_project_name = 'main'
 109
 110 html_show_copyright = False
 111
 112
 113 def setup(app):
 114     app.add_config_value('recommonmark_config', {
 115         # Crashes with sphinx
 116         'enable_inline_math': False,
 117         # We use it for testing/web-platform/tests
 118         'enable_eval_rst': True,
 119             }, True)
 120     app.add_stylesheet('custom_theme.css')
 121     app.add_transform(AutoStructify)