Documentation/conf.py

   1 # -*- coding: utf-8 -*-
   2 import subprocess
   3 from recommonmark.parser import CommonMarkParser
   4 import sphinx
   5
   6 # Get Sphinx version
   7 major = 0
   8 minor = 0
   9 patchlevel = 0
  10 version = sphinx.__version__.split(".")
  11 if len(version) > 1:
  12         major = int(version[0])
  13         minor = int(version[1])
  14         if len(version) > 2:
  15                 patchlevel = int(version[2])
  16
  17 # Add any paths that contain templates here, relative to this directory.
  18 templates_path = ['_templates']
  19
  20 # The suffix(es) of source filenames.
  21 source_suffix = ['.md']
  22
  23 # The master toctree document.
  24 master_doc = 'index'
  25
  26 # General information about the project.
  27 project = u'coreboot'
  28 copyright = u'CC-by 4.0 the coreboot project'
  29 author = u'the coreboot project'
  30
  31 # The version info for the project you're documenting, acts as replacement for
  32 # |version| and |release|, also used in various other places throughout the
  33 # built documents.
  34 #
  35 # The full version, including alpha/beta/rc tags.
  36 release = subprocess.check_output(('git', 'describe')).decode("utf-8")
  37 # The short X.Y version.
  38 version = release.split("-")[0]
  39
  40 extensions = []
  41 # Load recommonmark, supported since 1.8+
  42 if major >= 2 or (major == 1 and minor >= 8):
  43     extensions += ['recommonmark']
  44
  45 # Try to load DITAA
  46 try:
  47     import sphinxcontrib.ditaa
  48 except ImportError:
  49     print("Error: Please install sphinxcontrib.ditaa for ASCII art conversion\n")
  50 else:
  51     extensions += ['sphinxcontrib.ditaa']
  52
  53 # The language for content autogenerated by Sphinx. Refer to documentation
  54 # for a list of supported languages.
  55 #
  56 # This is also used if you do content translation via gettext catalogs.
  57 # Usually you set "language" from the command line for these cases.
  58 language = 'en'
  59
  60 # List of patterns, relative to source directory, that match files and
  61 # directories to ignore when looking for source files.
  62 # This patterns also effect to html_static_path and html_extra_path
  63 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
  64
  65 # The name of the Pygments (syntax highlighting) style to use.
  66 pygments_style = 'sphinx'
  67
  68 # A list of ignored prefixes for module index sorting.
  69 # modindex_common_prefix = []
  70
  71 # If true, keep warnings as "system message" paragraphs in the built documents.
  72 # keep_warnings = False
  73
  74 # If true, `todo` and `todoList` produce output, else they produce nothing.
  75 todo_include_todos = False
  76
  77
  78 # -- Options for HTML output ----------------------------------------------
  79
  80 # The theme to use for HTML and HTML Help pages.  See the documentation for
  81 # a list of builtin themes.
  82 #
  83 html_theme = 'sphinx_rtd_theme'
  84
  85 # Add any paths that contain custom static files (such as style sheets) here,
  86 # relative to this directory. They are copied after the builtin static files,
  87 # so a file named "default.css" will overwrite the builtin "default.css".
  88 html_static_path = ['_static']
  89
  90 html_css_files = [
  91     'theme_overrides.css',  # override wide tables in RTD theme
  92 ]
  93
  94 # Output file base name for HTML help builder.
  95 htmlhelp_basename = 'corebootdoc'
  96
  97 enable_auto_toc_tree = True
  98
  99 class MyCommonMarkParser(CommonMarkParser):
 100     # remove this hack once upstream RecommonMark supports inline code
 101     def visit_code(self, mdnode):
 102         from docutils import nodes
 103         n = nodes.literal(mdnode.literal, mdnode.literal)
 104         self.current_node.append(n)
 105
 106 def setup(app):
 107     from recommonmark.transform import AutoStructify
 108     # Load recommonmark on old Sphinx
 109     if major == 1 and minor < 8:
 110         app.add_source_parser('.md', MyCommonMarkParser)
 111
 112     app.add_config_value('recommonmark_config', {
 113         'enable_auto_toc_tree': True,
 114         'enable_auto_doc_ref': False, # broken in Sphinx 1.6+
 115         'enable_eval_rst': True,
 116         'url_resolver': lambda url: '/' + url
 117     }, True)
 118     app.add_transform(AutoStructify)