zammad-admin-documentation/conf.py at pre-release · zammad/zammad-admin-documentation · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
import sys
import os
import time

import sphinx_rtd_theme

html_logo = "images/zammad_logo_70x61@2x.png"
html_favicon = "images/favicon.ico"
project = u'Zammad Admin Documentation'
copyright = u'2012 - %s, Zammad Foundation' % time.strftime("%Y")
author = u'Zammad'

source_suffix = '.rst'
master_doc = 'index'
exclude_patterns = ['_build', 'html', 'doctrees']
extensions = [
      'versionwarning.extension',
      'sphinx_tabs.tabs',
      'sphinxcontrib.mermaid',
      'sphinx.ext.extlinks',
      'sphinx_copybutton',
   ]

locale_dirs = ['locale/']
gettext_compact = "admin-docs"
language = "en"

html_static_path = ['_static']

html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_extra_path = ['robots.txt']

html_css_files = [
   'https://media.readthedocs.org/css/sphinx_rtd_theme.css',
   'https://media.readthedocs.org/css/readthedocs-doc-embed.css',
   'theme/theme_overrides.css'
]

html_js_files = [
   'theme/zammad_overrides.js',
   'theme/mermaid.min.js'
]

# thanks to https://blog.deimos.fr/2014/10/02/sphinxdoc-and-readthedocs-theme-tricks-2/

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd:

   # We're running outside of readthedocs and expect the compiled version to match the Git branch.
   git_branch = os.environ.get('ZAMMAD_DOCS_GIT_BRANCH', None)

   if git_branch == 'main':
      branch = 'latest'
   else:
      branch = 'pre-release'

else:

   # Get current version we're on for possible version warning
   rtd_version = os.environ.get('READTHEDOCS_VERSION')

   # If we're **not on latest**, we'll display a deprecation warning.
   if rtd_version == 'latest':
      branch = rtd_version

      # Inject the language switcher script.
      html_js_files.append('theme/language_switcher.js')
   elif rtd_version == 'pre-release':
      branch = "pre-release"
   else:
      branch = "old-version"

# Ensure `version` config is set due to translation integration.
version = branch

# Default definitions for this documentations version warnings if applicable
# https://sphinx-version-warning.readthedocs.io/en/latest/configuration.html
versionwarning_project_slug = "zammad-admin-documentation"
versionwarning_admonition_type = "warning"
versionwarning_project_version = branch
versionwarning_body_selector = "div.document"

versionwarning_messages = {
   "pre-release": (
      "You're viewing a <strong>pre-release</strong> version of this "
      "documentation! If you want to see the stable, current version of "
      "this documentation, please see "
      '<a href="https://admin-docs.zammad.org/en/latest/" '
      'title="current documentation version">here</a>.'
   ),
   "old-version": (
      "You're viewing a <strong>deprecated</strong> version of Zammad's "
      "documentation. If you're still running that version, please consider "
      '<a href="https://docs.zammad.org/en/latest/install/update.html" '
      'title="Updating Zammad">Updating Zammad</a> asap.'
   ),
}

# Provide aliases to common external documentation targets.
#   It supports automatic substitution for the current branch placeholders,
#   but always links to the English translation.
#
#   :user-docs:`the user documentation </advanced/tabs.html>`
#   :docs:`the system documentation </appendix/configure-env-vars.html>`
#
#   which may render the following links:
#
#   https://user-docs.zammad.org/en/latest/advanced/tabs.html
#   https://docs.zammad.org/en/latest/appendix/configure-env-vars.html
#
#   Note the need for including the file extension as part of the path
#   relative to the documentation root!
#
extlinks = {
   'docs': (f'https://docs.zammad.org/en/{branch}%s', ''),
   'user-docs': (f'https://user-docs.zammad.org/en/{branch}%s', ''),
}

copybutton_exclude = '.gp'
copybutton_line_continuation_character = '\\'

# Copy button can be disabled by adding the `:class: no-copybutton` to the code block.
copybutton_selector = 'div:not(.no-copybutton) > div.highlight > pre'