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# -- Path setup -------------------------------------------------------------- 7# If extensions (or modules to document with autodoc) are in another directory, 8# add these directories to sys.path here. If the directory is relative to the 9# documentation root, use os.path.abspath to make it absolute, like shown here. 10# 11# import os 12# import sys 13# sys.path.insert(0, os.path.abspath('.')) 14import datetime 15import os 16 17import sphinx_material_saltstack 18from docutils import nodes 19from docutils.nodes import Element 20from sphinx.writers.html import HTMLTranslator 21 22 23# Force all external links to open as new tabs, 24# without breaking internal links. This causes 25# external links to work by default on HTML 26# generated sites, while natively working in PDF 27# output, also. 28# 29# Overwrites visit_reference() Sphinx method found 30# in HTMLTranslator class of sphinx/sphinx/writers/html.py 31# Solution Source: https://stackoverflow.com/a/61669375/5340149 32class PatchedHTMLTranslator(HTMLTranslator): 33 def visit_reference(self, node: Element) -> None: 34 atts = {"class": "reference"} 35 if node.get("internal") or "refuri" not in node: 36 atts["class"] += " internal" 37 else: 38 atts["class"] += " external" 39 # Customize behavior (open in new tab, secure linking site) 40 atts["target"] = "_blank" 41 atts["rel"] = "noopener noreferrer" 42 if "refuri" in node: 43 atts["href"] = node["refuri"] or "#" 44 if self.settings.cloak_email_addresses and atts["href"].startswith( 45 "mailto:" 46 ): 47 atts["href"] = self.cloak_mailto(atts["href"]) 48 self.in_mailto = True 49 else: 50 assert ( 51 "refid" in node 52 ), 'References must have "refuri" or "refid" attribute.' 53 atts["href"] = "#" + node["refid"] 54 if not isinstance(node.parent, nodes.TextElement): 55 assert len(node) == 1 and isinstance(node[0], nodes.image) 56 atts["class"] += " image-reference" 57 if "reftitle" in node: 58 atts["title"] = node["reftitle"] 59 if "target" in node: 60 atts["target"] = node["target"] 61 self.body.append(self.starttag(node, "a", "", **atts)) 62 63 if node.get("secnumber"): 64 self.body.append( 65 ("%s" + self.secnumber_suffix) % ".".join(map(str, node["secnumber"])) 66 ) 67 68 69# Run above custom function against links 70def setup(app): 71 app.set_translator("html", PatchedHTMLTranslator) 72 73 74this_year = datetime.datetime.today().year 75if this_year == 2020: 76 copyright_year = 2020 77else: 78 copyright_year = f"2020 - {this_year}" 79 80# -- Project information ----------------------------------------------------- 81project = "Tiamat" 82copyright = f"{copyright_year}, SaltStack, Inc." 83author = "SaltStack, Inc." 84 85# Variables to pass into the docs from sitevars.txt for rst substitution 86with open("sitevars.rst") as site_vars_file: 87 site_vars = site_vars_file.read().splitlines() 88 89rst_prolog = """ 90{} 91""".format( 92 "\n".join(site_vars[:]) 93) 94 95# The full version, including alpha/beta/rc tags 96# Version info -- read without importing 97with open("../tiamat/version.py") as version_file: 98 for line in version_file.readlines(): 99 if "version = " in line: 100 release = line.split(" ")[-1].replace("\n", "").replace('"', "") 101 102# -- General configuration --------------------------------------------------- 103 104# Add any Sphinx extension module names here, as strings. They can be 105# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 106# ones. 107extensions = [ 108 "sphinx_material_saltstack", 109 "sphinx_copybutton", 110 "sphinx-prompt", 111 "sphinx_substitution_extensions", 112] 113 114source_suffix = ".rst" 115 116# Add any paths that contain templates here, relative to this directory. 117templates_path = ["_templates"] 118 119# List of patterns, relative to source directory, that match files and 120# directories to ignore when looking for source files. 121# This pattern also affects html_static_path and html_extra_path. 122exclude_patterns = [ 123 "_build", 124 "Thumbs.db", 125 ".DS_Store", 126 ".vscode", 127 ".venv", 128 ".git", 129 ".gitlab-ci", 130 ".gitignore", 131 "sitevars.rst", 132] 133 134 135# -- Options for HTML output ---------------------------------------------- 136 137# The theme to use for HTML and HTML Help pages. See the documentation for 138# a list of builtin themes. 139# 140 141# Base Material Theme requirements 142html_show_sourcelink = True # False on private repos; True on public repos 143html_theme = "sphinx_material_saltstack" 144html_theme_path = sphinx_material_saltstack.html_theme_path() 145html_context = sphinx_material_saltstack.get_html_context() 146html_sidebars = { 147 "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"] 148} 149html_theme_options = { 150 # Set the name of the project to appear in the navigation. 151 "nav_title": "Tiamat", 152 # Set you GA account ID to enable tracking 153 # "google_analytics_account": "", 154 # Set the repo location to get a badge with stats (only if public repo) 155 "repo_url": "https://gitlab.com/saltstack/pop/tiamat", 156 "repo_name": "tiamat", 157 "repo_type": "gitlab", 158 # Visible levels of the global TOC; -1 means unlimited 159 "globaltoc_depth": 1, 160 # If False, expand all TOC entries 161 "globaltoc_collapse": False, 162 # If True, show hidden TOC entries 163 "globaltoc_includehidden": True, 164 # hide tabs? 165 "master_doc": False, 166 # Minify for smaller HTML/CSS assets 167 "html_minify": True, 168 "css_minify": True, 169} 170 171# Add any paths that contain custom static files (such as style sheets) here, 172# relative to this directory. They are copied after the builtin static files, 173# so a file named "default.css" will overwrite the builtin "default.css". 174html_static_path = ["_static"] 175 176# The name of an image file (relative to this directory) to place at the top 177# of the sidebar. 178html_logo = os.path.join( 179 html_theme_path[0], 180 "sphinx_material_saltstack", 181 "static", 182 "images", 183 "saltstack-logo.png", 184) 185 186# The name of an image file (within the static path) to use as favicon of the 187# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 188# pixels large. Favicons can be up to at least 228x228. PNG 189# format is supported as well, not just .ico' 190html_favicon = os.path.join( 191 html_theme_path[0], "sphinx_material_saltstack", "static", "images", "favicon.png", 192) 193 194### 195# PDF Generation / LaTeX configuration 196### 197latex_logo = "_static/images/salt-pdf-logo.png" 198 199# Linux Biolinum, Linux Libertine: http://www.linuxlibertine.org/ 200# Source Code Pro: https://github.com/adobe-fonts/source-code-pro/releases 201latex_elements = { 202 "inputenc": "", # use XeTeX instead of the inputenc LaTeX package. 203 "utf8extra": "", 204 "preamble": r""" 205 \usepackage{fontspec} 206 \setsansfont{Linux Biolinum O} 207 \setromanfont{Linux Libertine O} 208 \setmonofont{Source Code Pro} 209""", 210} 211