update sphynx config

docs/conf.py

@@ -1,88 +1,217 @@
 # -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/stable/config
 
-from __future__ import division, print_function, unicode_literals
+# -- Path setup --------------------------------------------------------------
 
-import os
+# If extensions (or modules to document with autodoc) are in another directory,
-import sys
+# add these directories to sys.path here. If the directory is relative to the
-
+# documentation root, use os.path.abspath to make it absolute, like shown here.
-#import sphinx_rtd_theme
+#
-from recommonmark.parser import CommonMarkParser
+# import os
-
+# import sys
-sys.path.insert(0, os.path.abspath('..'))
+# sys.path.insert(0, os.path.abspath('.'))
-sys.path.append(os.path.dirname(__file__))
+import logging
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "readthedocs.settings.dev")
+import os.path
+import re
+import subprocess
 
 
+logger = logging.getLogger('rtd-samples')
 
-sys.path.append(os.path.abspath('_ext'))
+
+def get_git_branch():
+    """Get the git branch this repository is currently on"""
+    path_to_here = os.path.abspath(os.path.dirname(__file__))
+
+    # Invoke git to get the current branch which we use to get the theme
+    try:
+        p = subprocess.Popen(['git', 'branch'], stdout=subprocess.PIPE, cwd=path_to_here)
+
+        # This will contain something like "* (HEAD detached at origin/MYBRANCH)"
+        # or something like "* MYBRANCH"
+        branch_output = p.communicate()[0]
+
+        # This is if git is in a normal branch state
+        match = re.search(r'\* (?P<branch_name>[^\(\)\n ]+)', branch_output)
+        if match:
+            return match.groupdict()['branch_name']
+
+        # git is in a detached HEAD state
+        match = re.search(r'\(HEAD detached at origin/(?P<branch_name>[^\)]+)\)', branch_output)
+        if match:
+            return match.groupdict()['branch_name']
+    except Exception:
+        logger.exception(u'Could not get the branch')
+
+    # Couldn't figure out the branch probably due to an error
+    return None
+
+
+# -- Project information -----------------------------------------------------
+
+project = u'BrailleRAP'
+copyright = u'CERN licence V1.2'
+author = u'BrailleRAP team'
+
+# The short X.Y version
+version = u'6.5'
+# The full version, including alpha/beta/rc tags
+release = u'6.5'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.intersphinx',
-	'sphinx.ext.autosectionlabel',
-    'sphinx_rtd_theme',
-    
 ]
+
+# Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-source_suffix = ['.rst', '.md']
+# The suffix(es) of source filenames.
-source_parsers = {
+# You can specify multiple suffix as a list of string:
-    '.md': CommonMarkParser,
+#
-}
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
 
+# The master toctree document.
 master_doc = 'index'
-project = u'BrailleRap'
-copyright = '2018-{}, BrailleRap'
 
-version = '6.5.0'
+# The language for content autogenerated by Sphinx. Refer to documentation
-release = '6.5.0'
+# for a list of supported languages.
-exclude_patterns = ['_build']
+#
-default_role = 'obj'
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = fr
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-#intersphinx_mapping = {
-#    'python': ('http://python.readthedocs.io/en/latest/', None),
-#    'django': ('http://django.readthedocs.io/en/1.8.x/', None),
-#    'sphinx': ('http://sphinx.readthedocs.io/en/latest/', None),
-#}
-htmlhelp_basename = 'BrailleRapdoc'
-latex_documents = [
-    ('index', 'BrailleRap.tex', u'BrailleRap Documentation',
-     u'BrailleRap Team', 'manual'),
-]
 
-#man_pages = [
+# -- Options for HTML output -------------------------------------------------
-#    ('index', 'read-the-docs', u'Read the Docs Documentation',
-#     [u'Eric Holscher, Charlie Leifer, Bobby Grace'], 1)
-#]
 
-exclude_patterns = [
+# Maps git branches to Sphinx themes
-    # 'api' # needed for ``make gettext`` to not die.
+default_html_theme = 'sphinx_rtd_theme'
-]
+branch_to_theme_mapping = {
+    # 3rd party themes
+    'master': default_html_theme,
 
-language = 'fr' 
+    # Sphinx built-in themes
+    'alabaster': 'alabaster',
+    'classic': 'classic',
+    'sphinxdoc': 'sphinxdoc',
+    'scrolls': 'scrolls',
+    'agogo': 'agogo',
+    'traditional': 'traditional',
+    'nature': 'nature',
+    'haiku': 'haiku',
+    'pyramid': 'pyramid',
+    'bizstyle': 'bizstyle',
+}
+current_branch = None #get_git_branch()
 
-locale_dirs = [
+if current_branch:
-    'locale/',
+    sphinx_html_theme = branch_to_theme_mapping.get(current_branch, default_html_theme)
-]
+    print(u'Got theme {} from branch {}'.format(sphinx_html_theme, current_branch))
-gettext_compact = False
+else:
-gettext_uuid = False
+    sphinx_html_theme = default_html_theme
+    print(u'Error getting current branch - using default theme')
 
-html_theme = 'sphinx_rtd_theme'
+# The theme to use for HTML and HTML Help pages.  See the documentation for
-#html_static_path = ['_static']
+# a list of builtin themes.
-#html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+#
-#html_theme_path = ["_themes"]
+html_theme = sphinx_html_theme
-#html_logo = 'IMG/logo.svg' 
 
-html_theme_options = {
+# Theme options are theme-specific and customize the look and feel of a theme
-    'logo_only': False,
+# further.  For a list of options available for each theme, see the
-    'display_version': True,
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'BrailleRAPdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
 }
 
-
+# Grouping the document tree into LaTeX files. List of tuples
-def setup(app):
+# (source start file, target name, title,
-    #app.add_stylesheet('css/custom.css')
+#  author, documentclass [howto, manual, or own class]).
-    app.add_css_file('css/custom.css')
+latex_documents = [
-    pass
+    (master_doc, 'BrailleRAP.tex', project,
+     u'BrailleRAP team', 'manual'),
+]
 
 
+# -- Options for manual page output ------------------------------------------
 
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'BrailleRAPman', project,
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'BrailleRAPtexinfo', project,
+     author, 'BrailleRAPtexinfo', 'Open source DIY Braille embosser.',
+     'Miscellaneous'),
+]