conf.py (5140B)
1 # Configuration file for the Sphinx documentation builder. 2 # 3 # This file only contains a selection of the most common options. For a full 4 # list see the documentation: 5 # https://www.sphinx-doc.org/en/master/usage/configuration.html 6 7 # -- Path setup -------------------------------------------------------------- 8 9 # If extensions (or modules to document with autodoc) are in another directory, 10 # add these directories to sys.path here. If the directory is relative to the 11 # documentation root, use os.path.abspath to make it absolute, like shown here. 12 # 13 import os 14 import sys 15 # sys.path.insert(0, os.path.abspath('.')) 16 17 18 # -- Project information ----------------------------------------------------- 19 20 project = 'HIGHWAY' 21 22 # The full version, including alpha/beta/rc tags 23 release = 'nightly' 24 copyright = 'Apache 2' 25 26 27 # -- General configuration --------------------------------------------------- 28 29 # Add any Sphinx extension module names here, as strings. They can be 30 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 31 # ones. 32 extensions = [ 33 'sphinx_rtd_theme', 34 'sphinx.ext.githubpages', 35 'sphinx.ext.autosectionlabel', 36 'sphinx_tabs.tabs', 37 ] 38 39 # Add any paths that contain templates here, relative to this directory. 40 templates_path = ['_templates'] 41 42 # List of patterns, relative to source directory, that match files and 43 # directories to ignore when looking for source files. 44 # This pattern also affects html_static_path and html_extra_path. 45 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 46 47 48 # -- Options for HTML output ------------------------------------------------- 49 50 # The theme to use for HTML and HTML Help pages. See the documentation for 51 # a list of builtin themes. 52 # 53 html_theme = 'sphinx_rtd_theme' 54 55 # Add any paths that contain custom static files (such as style sheets) here, 56 # relative to this directory. They are copied after the builtin static files, 57 # so a file named "default.css" will overwrite the builtin "default.css". 58 html_static_path = ['_static'] 59 html_logo = 'images/logo.png' 60 html_favicon = 'images/logo-32x32.ico' 61 html_theme_options = { 62 'logo_only': False, 63 'display_version': True, 64 } 65 # The top toctree document. 66 top_doc = 'index' 67 68 # Add any extra paths that contain custom files (such as robots.txt or 69 # .htaccess) here, relative to this directory. These files are copied 70 # directly to the root of the documentation. 71 html_extra_path = ["_static/css"] 72 73 html_css_files = ["css/toggle.css"] 74 html_js_files = ["js/toggle.js"] 75 76 ############################ 77 # SETUP THE RTD LOWER-LEFT # 78 ############################ 79 try: 80 html_context 81 except NameError: 82 html_context = dict() 83 html_context['display_lower_left'] = True 84 85 if 'REPO_NAME' in os.environ: 86 REPO_NAME = os.environ['REPO_NAME'] 87 else: 88 REPO_NAME = '' 89 90 # SET CURRENT_LANGUAGE 91 if 'current_language' in os.environ: 92 # get the current_language env var set by buildDocs.sh 93 current_language = os.environ['current_language'] 94 else: 95 # the user is probably doing `make html` 96 # set this build's current language to english 97 current_language = 'en' 98 99 # tell the theme which language to we're currently building 100 html_context['current_language'] = current_language 101 102 # SET CURRENT_VERSION 103 from git import Repo 104 repo = Repo( search_parent_directories=True ) 105 106 if 'current_version' in os.environ: 107 # get the current_version env var set by buildDocs.sh 108 current_version = os.environ['current_version'] 109 else: 110 # the user is probably doing `make html` 111 # set this build's current version by looking at the branch 112 current_version = repo.active_branch.name 113 114 # tell the theme which version we're currently on ('current_version' affects 115 # the lower-left rtd menu and 'version' affects the logo-area version) 116 html_context['current_version'] = current_version 117 html_context['version'] = current_version 118 119 # POPULATE LINKS TO OTHER LANGUAGES 120 html_context['languages'] = [ ('en', '/' +REPO_NAME+ '/en/' +current_version+ '/') ] 121 122 languages = [lang.name for lang in os.scandir('locales') if lang.is_dir()] 123 for lang in languages: 124 html_context['languages'].append( (lang, '/' +REPO_NAME+ '/' +lang+ '/' +current_version+ '/') ) 125 126 # POPULATE LINKS TO OTHER VERSIONS 127 html_context['versions'] = list() 128 129 versions = [branch.name for branch in repo.branches] 130 for version in versions: 131 html_context['versions'].append( (version, '/' +REPO_NAME+ '/' +current_language+ '/' +version+ '/') ) 132 133 # POPULATE LINKS TO OTHER FORMATS/DOWNLOADS 134 135 # settings for creating PDF with rinoh 136 rinoh_documents = [( 137 top_doc, 138 'target', 139 project+ ' Documentation', 140 '© ' +copyright, 141 )] 142 today_fmt = "%B %d, %Y" 143 144 # settings for EPUB 145 epub_basename = 'target' 146 147 html_context['downloads'] = list() 148 149 html_context['downloads'].append( ('epub', '/' +REPO_NAME+ '/' +current_language+ '/' +current_version+ '/' +REPO_NAME+ '_' +current_language+ '_' +current_version+ '.epub') ) 150 151 ########################## 152 # "EDIT ON GITHUB" LINKS # 153 ########################## 154 155 html_context['display_github'] = True 156 html_context['github_user'] = 'google' 157 html_context['github_repo'] = REPO_NAME 158 html_context['github_version'] = 'master/docs/'