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