blob: e2bbbbc688ca7f7c5771e3a5969330e669f7dd80 [file] [log] [blame]
Zack Williams98fe2322021-09-20 15:02:11 -07001# -*- coding: utf-8 -*-
2#
3# Configuration file for the Sphinx documentation builder.
4#
5# This file does only contain a selection of the most common options. For a
6# full list see the documentation:
7# http://www.sphinx-doc.org/en/master/config
8
9# -- Path setup --------------------------------------------------------------
10
11# If extensions (or modules to document with autodoc) are in another directory,
12# add these directories to sys.path here. If the directory is relative to the
13# documentation root, use os.path.abspath to make it absolute, like shown here.
14#
15# import os
16# import sys
17# sys.path.insert(0, os.path.abspath('.'))
18
19import os
20
21def get_version():
22 with open("VERSION") as f:
23 return f.read().strip()
24
25# -- Project information -----------------------------------------------------
26
27project = u'SD-Fabric Docs'
28copyright = u'2021-current, Open Networking Foundation'
29author = u'Open Networking Foundation'
30
31# The short X.Y version
32version = get_version()
33
34# The full version, including alpha/beta/rc tags
35release = version
36
37# -- General configuration ---------------------------------------------------
38
39# If your documentation needs a minimal Sphinx version, state it here.
40#
41# needs_sphinx = '1.0'
42
43# make all warnings errors
44warning_is_error = True
45
46# Add any Sphinx extension module names here, as strings. They can be
47# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
48# ones.
49extensions = [
50 'sphinx.ext.autosectionlabel',
51 'sphinx.ext.coverage',
52 'sphinx.ext.graphviz',
53 'sphinx.ext.ifconfig',
54 'sphinx.ext.intersphinx',
55 'sphinx.ext.mathjax',
56 'sphinx.ext.todo',
57 'sphinxcontrib.spelling',
58 "sphinx_multiversion",
59]
60
61# require document prefix on section labels
62autosectionlabel_prefix_document = True
63
64# Text files with lists of words that shouldn't fail the spellchecker:
65spelling_word_list_filename=['dict.txt', ]
66
67# sphinx-multiversion prep, run in each versioned source directory
68prep_commands = [
69]
70
Daniele Moroed033562021-10-04 16:12:31 +020071# include only the branches matching master and sdfabric-*
Zack Williams98fe2322021-09-20 15:02:11 -070072smv_branch_whitelist = r'^(master|sdfabric-.*)$'
73
74# include all remote branches
75smv_remote_whitelist = r'^.*$'
76
77# Add any paths that contain templates here, relative to this directory.
78templates_path = ['_templates']
79
80# The suffix(es) of source filenames.
81# You can specify multiple suffix as a list of string:
82#
83# source_suffix = ['.rst', '.md']
84source_suffix = ['.rst']
85
86# The master toctree document.
87master_doc = 'index'
88
89# The language for content autogenerated by Sphinx. Refer to documentation
90# for a list of supported languages.
91#
92# This is also used if you do content translation via gettext catalogs.
93# Usually you set "language" from the command line for these cases.
94language = None
95
96# List of patterns, relative to source directory, that match files and
97# directories to ignore when looking for source files.
98# This pattern also affects html_static_path and html_extra_path.
99exclude_patterns = [
100 '*/LICENSE.md',
101 '*/vendor',
102 '.DS_Store',
103 'Thumbs.db',
104 '_build',
105 'venv-docs',
106 'requirements.txt',
107]
108
109# The name of the Pygments (syntax highlighting) style to use.
110pygments_style = None
111
112# -- Options for HTML output -------------------------------------------------
113
114# The theme to use for HTML and HTML Help pages. See the documentation for
115# a list of builtin themes.
116#
117html_theme = 'sphinx_rtd_theme'
118
119# html_logo = '_static/sdfabric.svg'
120
121html_favicon = '_static/sdfabric-favicon-128.png'
122
123# Theme options are theme-specific and customize the look and feel of a theme
124# further. For a list of options available for each theme, see the
125# documentation.
126#
127# html_theme_options = {
128# 'logo_only': True
129# }
130
131# Add any paths that contain custom static files (such as style sheets) here,
132# relative to this directory. They are copied after the builtin static files,
133# so a file named "default.css" will overwrite the builtin "default.css".
134html_static_path = ['_static']
135
136# Custom sidebar templates, must be a dictionary that maps document names
137# to template names.
138#
139# The default sidebars (for documents that don't match any pattern) are
140# defined by theme itself. Builtin themes are using these templates by
141# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
142# 'searchbox.html']``.
143#
144# html_sidebars = {}
145
146# -- Options for HTMLHelp output ---------------------------------------------
147
148# Output file base name for HTML help builder.
149htmlhelp_basename = 'SDFabricDocs'
150
151
152# -- Options for LaTeX output ------------------------------------------------
153
154latex_elements = {
155 # The paper size ('letterpaper' or 'a4paper').
156 #
157 # 'papersize': 'letterpaper',
158
159 # The font size ('10pt', '11pt' or '12pt').
160 #
161 # 'pointsize': '10pt',
162
163 # Additional stuff for the LaTeX preamble.
164 #
165 # 'preamble': '',
166
167 # Latex figure (float) alignment
168 #
169 # 'figure_align': 'htbp',
170}
171
172# Grouping the document tree into LaTeX files. List of tuples
173# (source start file, target name, title,
174# author, documentclass [howto, manual, or own class]).
175latex_documents = [
176 (master_doc, 'SD-FabricDocs.tex', u'SD-Fabric Docs',
177 u'ONF', 'manual'),
178]
179
180
181# -- Options for manual page output ------------------------------------------
182
183# One entry per manual page. List of tuples
184# (source start file, name, description, authors, manual section).
185man_pages = [
186 (master_doc, 'SD-Fabric Docs', u'SD-Fabric Docs',
187 [author], 1)
188]
189
190
191# -- Options for Texinfo output ----------------------------------------------
192
193# Grouping the document tree into Texinfo files. List of tuples
194# (source start file, target name, title, author,
195# dir menu entry, description, category)
196texinfo_documents = [
197 (master_doc, 'SD-Fabric Docs', u'SD-Fabric Docs',
198 author, 'SD-FabricDocs', 'One line description of project.',
199 'Miscellaneous'),
200]
201
202
203# -- Options for Epub output -------------------------------------------------
204
205# Bibliographic Dublin Core info.
206epub_title = project
207
208# The unique identifier of the text. This can be a ISBN number
209# or the project homepage.
210#
211# epub_identifier = ''
212
213# A unique identification for the text.
214#
215# epub_uid = ''
216
217# A list of files that should not be packed into the epub file.
218epub_exclude_files = ['search.html']
219
220
221# -- Extension configuration -------------------------------------------------
222
223# blockdiag/etc. config
224
225rackdiag_antialias = True
226rackdiag_html_image_format = "SVG"
227rackdiag_fontpath = [
228 "_static/fonts/Inconsolata-Regular.ttf",
229 "_static/fonts/Inconsolata-Bold.ttf",
230]
231
232nwdiag_antialias = True
233nwdiag_html_image_format = "SVG"
234nwdiag_fontpath = [
235 "_static/fonts/Inconsolata-Regular.ttf",
236 "_static/fonts/Inconsolata-Bold.ttf",
237]
238
239# -- Options for todo extension ----------------------------------------------
240# If true, `todo` and `todoList` produce output, else they produce nothing.
241todo_include_todos = True
242
243# -- Options for linkcheck ---------------------------------------------------
244# The link checker strips off .md from links and then complains
245linkcheck_ignore = [
Daniele Morobba6faa2021-10-07 14:18:06 +0200246 r'https://github.com/stratum/fabric-tna/*', # Fabric-TNA private repo
247 r'https://github.com/opennetworkinglab/sdfabric-utils', # Private repo
Jon Hallced4be72021-10-04 10:19:04 -0700248 r'https://github.com/omec-project/up4/*', # UP4 private repo
249 r'https://jenkins.aetherproject.org/view/SD-Fabric%20Nightly%20Tests/' # Jenkins View, requires login
Zack Williams98fe2322021-09-20 15:02:11 -0700250]
251
252linkcheck_timeout = 3
253linkcheck_retries = 2
254
Yi Tseng22e7dbc2021-09-28 14:32:15 -0700255linkcheck_anchors_ignore = [
256 r"L\d+" # Ignore line anchors from GitHub.
257]
258
Zack Williams98fe2322021-09-20 15:02:11 -0700259# -- options for Intersphinx extension ---------------------------------------
260
261intersphinx_mapping = {
262 'ansible': ('https://docs.ansible.com/ansible/latest', None),
263 'sphinx': ('https://www.sphinx-doc.org/en/master', None),
264 'trellis': ('https://docs.trellisfabric.org/master', None),
265 'sysapproach5g': ('https://5g.systemsapproach.org/', None),
266 'sysapproachnet': ('https://book.systemsapproach.org/', None),
267 'sysapproachsdn': ('https://sdn.systemsapproach.org/', None),
268 }
269
270def setup(app):
271
272 app.add_css_file('css/rtd_theme_mods.css')