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