tools/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 unicode_literals
   6
   7 import os
   8 import re
   9 import sys
  10
  11 from recommonmark.parser import CommonMarkParser
  12
  13 from datetime import datetime
  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.graphviz',
  39     'sphinx.ext.napoleon',
  40     'sphinx.ext.todo',
  41     'mozbuild.sphinx',
  42     'sphinx_js',
  43 ]
  44
  45 # JSDoc must run successfully for dirs specified, so running
  46 # tree-wide (the default) will not work currently.
  47 js_source_path = [
  48     'browser/components/extensions',
  49     'testing/marionette',
  50     'toolkit/components/extensions',
  51     'toolkit/components/extensions/parent',
  52     'toolkit/components/featuregates',
  53     'toolkit/mozapps/extensions',
  54 ]
  55 root_for_relative_js_paths = '.'
  56 jsdoc_config_path = 'tools/docs/jsdoc.json'
  57
  58 templates_path = ['_templates']
  59 source_suffix = '.rst'
  60 source_suffix = ['.rst', '.md']
  61 source_parsers = {
  62    '.md': CommonMarkParser,
  63 }
  64 master_doc = 'index'
  65 project = u'Mozilla Source Tree Docs'
  66 year = datetime.now().year
  67
  68 # Grab the version from the source tree's milestone.
  69 # FUTURE Use Python API from bug 941299.
  70 with open(os.path.join(topsrcdir, 'config', 'milestone.txt'), 'rt') as fh:
  71     for line in fh:
  72         line = line.strip()
  73
  74         if not line or line.startswith('#'):
  75             continue
  76
  77         release = line
  78         break
  79
  80 version = re.sub(r'[ab]\d+$', '', release)
  81
  82 exclude_patterns = ['_build', '_staging', '_venv']
  83 pygments_style = 'sphinx'
  84
  85 # We need to perform some adjustment of the settings and environment
  86 # when running on Read The Docs.
  87 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
  88
  89 if on_rtd:
  90     # SHELL isn't set on RTD and mach.mixin.process's import raises if a
  91     # shell-related environment variable can't be found. Set the variable here
  92     # to hack us into working on RTD.
  93     assert 'SHELL' not in os.environ
  94     os.environ['SHELL'] = '/bin/bash'
  95 else:
  96     # We only need to set the RTD theme when not on RTD because the RTD
  97     # environment handles this otherwise.
  98     import sphinx_rtd_theme
  99     html_theme = 'sphinx_rtd_theme'
 100     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 101
 102
 103 html_static_path = ['_static']
 104 htmlhelp_basename = 'MozillaTreeDocs'
 105
 106 moz_project_name = 'main'