blob: 7969551b49f7165dc2c5b4dc956250f51473955e [file] [log] [blame]
Zack Williams071eda22019-05-15 18:19:51 -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
Zack Williams16042b62020-03-29 22:03:16 -070019import os
20
21def get_version():
22 with open("VERSION") as f:
23 return f.read().strip()
24
Zack Williams071eda22019-05-15 18:19:51 -070025# -- Project information -----------------------------------------------------
26
27project = u'VOLTHA Docs'
Zack Williams76a16312021-09-14 06:50:44 -070028copyright = u'2019-2021, VOLTHA Contributors & Open Networking Foundation'
Zack Williams071eda22019-05-15 18:19:51 -070029author = u'VOLTHA Contributors'
30
31# The short X.Y version
Zack Williams16042b62020-03-29 22:03:16 -070032version = get_version()
Zack Williams071eda22019-05-15 18:19:51 -070033
34# The full version, including alpha/beta/rc tags
Zack Williams88df4742019-12-20 08:24:47 -070035release = version
Zack Williams071eda22019-05-15 18:19:51 -070036
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 'recommonmark',
51 'sphinx.ext.coverage',
52 'sphinx.ext.graphviz',
53 'sphinx.ext.ifconfig',
54 'sphinx.ext.mathjax',
55 'sphinx.ext.todo',
Zack Williamsc6460c22019-12-18 14:54:43 -070056 'sphinxcontrib.spelling',
Zack Williams16042b62020-03-29 22:03:16 -070057 "sphinx_multiversion",
Matteo Scandoloef5d6f42020-07-27 16:46:38 -070058 "sphinx.ext.intersphinx",
Andrea Campanella9a859842021-09-10 12:01:38 +020059 "sphinxcontrib.openapi",
Zack Williams071eda22019-05-15 18:19:51 -070060]
61
62# API documentation
63# https://github.com/rtfd/sphinx-autoapi
64# https://sphinx-autoapi.readthedocs.io
65# autoapi_type = 'go'
66# autoapi_dirs = [
67# 'voltha-go/cli/util',
68# 'voltha-go/rw_core/config',
69# 'voltha-go/rw_core/core',
70# 'voltha-go/rw_core/graph',
71# 'voltha-go/rw_core/utils',
72# ]
73
Zack Williamsc6460c22019-12-18 14:54:43 -070074# Text files with lists of words that shouldn't fail the spellchecker:
75spelling_word_list_filename=['dict.txt', ]
76
Zack Williams16042b62020-03-29 22:03:16 -070077# sphinx-multiversion prep, run in each versioned source directory
78prep_commands = [
Zack Williams88df4742019-12-20 08:24:47 -070079 'ln -sf _root_/repos _target_/repos',
80 'make prep',
81]
82
Zack Williams76a16312021-09-14 06:50:44 -070083# don't include tags
84smv_tag_whitelist = None
85
Zack Williams76744322020-04-09 22:00:35 -070086# inlcude only the branches matching master and voltha-*
87smv_branch_whitelist = r'^(master|voltha-.*)$'
88
89# include all remote branches
90smv_remote_whitelist = r'^.*$'
91
Zack Williams071eda22019-05-15 18:19:51 -070092# Add any paths that contain templates here, relative to this directory.
93templates_path = ['_templates']
94
95# The suffix(es) of source filenames.
96# You can specify multiple suffix as a list of string:
97#
98# source_suffix = ['.rst', '.md']
99source_suffix = ['.rst', '.md']
100
101# The master toctree document.
102master_doc = 'index'
103
104# The language for content autogenerated by Sphinx. Refer to documentation
105# for a list of supported languages.
106#
107# This is also used if you do content translation via gettext catalogs.
108# Usually you set "language" from the command line for these cases.
109language = None
110
111# List of patterns, relative to source directory, that match files and
112# directories to ignore when looking for source files.
113# This pattern also affects html_static_path and html_extra_path.
114exclude_patterns = [
115 '*/LICENSE.md',
Matteo Scandoloef5d6f42020-07-27 16:46:38 -0700116 '*/RELEASE_NOTES.md',
Zack Williams071eda22019-05-15 18:19:51 -0700117 '*/vendor',
118 '.DS_Store',
119 'Thumbs.db',
120 '_build',
Zack Williams16042b62020-03-29 22:03:16 -0700121 'venv_docs',
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100122 'voltha-system-tests/vst_venv',
Zack Williams16042b62020-03-29 22:03:16 -0700123 'voltha-go/BUILD.md',
Andy Bavier39d67b12020-02-27 16:08:52 -0700124 'cord-tester/venv_cord',
125 'cord-tester/docs',
126 'cord-tester/src',
127 'cord-tester/README.md',
128 'cord-tester/cord-robot/README.rst',
Zack Williams16042b62020-03-29 22:03:16 -0700129 'openolt/agent/*',
Zack Williams071eda22019-05-15 18:19:51 -0700130 'repos',
131 'requirements.txt',
132 'bbsim/README.md',
Zack Williamsf2391542019-12-11 15:49:19 -0700133 'CODE_OF_CONDUCT.md',
134 '*/CODE_OF_CONDUCT.md',
Matteo Scandoloef5d6f42020-07-27 16:46:38 -0700135 'doc_venv/*'
Zack Williams071eda22019-05-15 18:19:51 -0700136]
137
138# The name of the Pygments (syntax highlighting) style to use.
139pygments_style = None
140
141# -- Options for HTML output -------------------------------------------------
142
143# The theme to use for HTML and HTML Help pages. See the documentation for
144# a list of builtin themes.
145#
146html_theme = 'sphinx_rtd_theme'
147
Zack Williams16042b62020-03-29 22:03:16 -0700148html_logo = '_static/voltha.svg'
149
150html_favicon = '_static/voltha-favicon-128.png'
151
Zack Williams071eda22019-05-15 18:19:51 -0700152# Theme options are theme-specific and customize the look and feel of a theme
153# further. For a list of options available for each theme, see the
154# documentation.
155#
Zack Williams16042b62020-03-29 22:03:16 -0700156html_theme_options = {
157 'logo_only': True
158}
Zack Williams071eda22019-05-15 18:19:51 -0700159
160# Add any paths that contain custom static files (such as style sheets) here,
161# relative to this directory. They are copied after the builtin static files,
162# so a file named "default.css" will overwrite the builtin "default.css".
163html_static_path = ['_static']
164
165# Custom sidebar templates, must be a dictionary that maps document names
166# to template names.
167#
168# The default sidebars (for documents that don't match any pattern) are
169# defined by theme itself. Builtin themes are using these templates by
170# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
171# 'searchbox.html']``.
172#
173# html_sidebars = {}
174
175
Zack Williams16042b62020-03-29 22:03:16 -0700176
Zack Williams071eda22019-05-15 18:19:51 -0700177# -- Options for HTMLHelp output ---------------------------------------------
178
179# Output file base name for HTML help builder.
180htmlhelp_basename = 'VOLTHADocs'
181
182
183# -- Options for LaTeX output ------------------------------------------------
184
185latex_elements = {
186 # The paper size ('letterpaper' or 'a4paper').
187 #
188 # 'papersize': 'letterpaper',
189
190 # The font size ('10pt', '11pt' or '12pt').
191 #
192 # 'pointsize': '10pt',
193
194 # Additional stuff for the LaTeX preamble.
195 #
196 # 'preamble': '',
197
198 # Latex figure (float) alignment
199 #
200 # 'figure_align': 'htbp',
201}
202
203# Grouping the document tree into LaTeX files. List of tuples
204# (source start file, target name, title,
205# author, documentclass [howto, manual, or own class]).
206latex_documents = [
207 (master_doc, 'VOLTHADocs.tex', u'VOLTHA Docs',
208 u'VOLTHA Team', 'manual'),
209]
210
211
212# -- Options for manual page output ------------------------------------------
213
214# One entry per manual page. List of tuples
215# (source start file, name, description, authors, manual section).
216man_pages = [
217 (master_doc, 'VOLTHA Docs', u'VOLTHA Docs',
218 [author], 1)
219]
220
221
222# -- Options for Texinfo output ----------------------------------------------
223
224# Grouping the document tree into Texinfo files. List of tuples
225# (source start file, target name, title, author,
226# dir menu entry, description, category)
227texinfo_documents = [
228 (master_doc, 'VOLTHA Docs', u'VOLTHA Docs',
229 author, 'VOLTHADocs', 'One line description of project.',
230 'Miscellaneous'),
231]
232
233
234# -- Options for Epub output -------------------------------------------------
235
236# Bibliographic Dublin Core info.
237epub_title = project
238
239# The unique identifier of the text. This can be a ISBN number
240# or the project homepage.
241#
242# epub_identifier = ''
243
244# A unique identification for the text.
245#
246# epub_uid = ''
247
248# A list of files that should not be packed into the epub file.
249epub_exclude_files = ['search.html']
250
251
252# -- Extension configuration -------------------------------------------------
253
254# blockdiag/etc. config
255
256rackdiag_antialias = True
257rackdiag_html_image_format = "SVG"
258rackdiag_fontpath = [
259 "_static/fonts/Inconsolata-Regular.ttf",
260 "_static/fonts/Inconsolata-Bold.ttf",
261]
262
263nwdiag_antialias = True
264nwdiag_html_image_format = "SVG"
265nwdiag_fontpath = [
266 "_static/fonts/Inconsolata-Regular.ttf",
267 "_static/fonts/Inconsolata-Bold.ttf",
268]
269
270# -- Options for todo extension ----------------------------------------------
271# If true, `todo` and `todoList` produce output, else they produce nothing.
272todo_include_todos = True
273
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100274# -- Options for linkcheck ---------------------------------------------------
275# The link checker strips off .md from links and then complains
276linkcheck_ignore = [r'https://github.com/ciena/kind-voltha/blob/master/README',
277 r'https://github.com/opencord/voltctl/blob/master/LICENSE',
Zack Williams16042b62020-03-29 22:03:16 -0700278 r'https://github.com/ciena/kind-voltha#voltha-up-configuration-options',
279 r'https://www.sphinx-doc.org',
Andrea Campanella9f534c72021-03-19 18:44:27 +0100280 r'https://github.com/opencord/bbsim/blob/master/docs/source/DMI_Server_README',
281 r'https://github.com/opencord/kind-voltha/blob/master/README'
Zack Williams16042b62020-03-29 22:03:16 -0700282 ]
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100283
Zack Williams071eda22019-05-15 18:19:51 -0700284# -- Configure recommonmark to use AutoStructify -----------------------------
285# Docs: https://recommonmark.readthedocs.io/en/latest/auto_structify.html
286
287import recommonmark
288from recommonmark.transform import AutoStructify
289
290github_doc_root = 'https://github.com/opencord/voltha-docs'
291
292def setup(app):
293
294 app.add_css_file('css/rtd_theme_mods.css')
295
296 app.add_config_value('recommonmark_config', {
297 'url_resolver': lambda url: github_doc_root + url,
298 'auto_toc_tree_section': 'Contents',
299 }, True)
300
301 app.add_transform(AutoStructify)