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