blob: 8cb9c93510517ee630a8e8992f719d106e40a915 [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.
Zack Williams071eda22019-05-15 18:19:51 -070014
Zack Williams16042b62020-03-29 22:03:16 -070015import os
16
17def get_version():
18 with open("VERSION") as f:
19 return f.read().strip()
20
Zack Williams071eda22019-05-15 18:19:51 -070021# -- Project information -----------------------------------------------------
22
23project = u'VOLTHA Docs'
Joey Armstrongbbd71d62022-10-12 11:51:35 -040024copyright = u'2019-2022, VOLTHA Contributors & Open Networking Foundation'
Zack Williams071eda22019-05-15 18:19:51 -070025author = u'VOLTHA Contributors'
26
27# The short X.Y version
Zack Williams16042b62020-03-29 22:03:16 -070028version = get_version()
Zack Williams071eda22019-05-15 18:19:51 -070029# The full version, including alpha/beta/rc tags
Zack Williams88df4742019-12-20 08:24:47 -070030release = version
Zack Williams071eda22019-05-15 18:19:51 -070031
32# -- General configuration ---------------------------------------------------
33
34# If your documentation needs a minimal Sphinx version, state it here.
35#
36# needs_sphinx = '1.0'
37
38# make all warnings errors
39warning_is_error = True
40
41# Add any Sphinx extension module names here, as strings. They can be
42# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
43# ones.
44extensions = [
45 'recommonmark',
46 'sphinx.ext.coverage',
Joey Armstrongbbd71d62022-10-12 11:51:35 -040047 'sphinx.ext.extlinks',
Zack Williams071eda22019-05-15 18:19:51 -070048 'sphinx.ext.graphviz',
49 'sphinx.ext.ifconfig',
50 'sphinx.ext.mathjax',
51 'sphinx.ext.todo',
Zack Williamsc6460c22019-12-18 14:54:43 -070052 'sphinxcontrib.spelling',
Zack Williams16042b62020-03-29 22:03:16 -070053 "sphinx_multiversion",
Matteo Scandoloef5d6f42020-07-27 16:46:38 -070054 "sphinx.ext.intersphinx",
Andrea Campanellac18d1182021-09-10 12:01:38 +020055 "sphinxcontrib.openapi",
Zack Williams071eda22019-05-15 18:19:51 -070056]
57
58# API documentation
59# https://github.com/rtfd/sphinx-autoapi
60# https://sphinx-autoapi.readthedocs.io
61# autoapi_type = 'go'
62# autoapi_dirs = [
63# 'voltha-go/cli/util',
64# 'voltha-go/rw_core/config',
65# 'voltha-go/rw_core/core',
66# 'voltha-go/rw_core/graph',
67# 'voltha-go/rw_core/utils',
68# ]
69
Zack Williamsc6460c22019-12-18 14:54:43 -070070# Text files with lists of words that shouldn't fail the spellchecker:
71spelling_word_list_filename=['dict.txt', ]
72
Joey Armstrongbbd71d62022-10-12 11:51:35 -040073#sphinx-multiversion prep, run in each versioned source directory
Zack Williams16042b62020-03-29 22:03:16 -070074prep_commands = [
Zack Williams88df4742019-12-20 08:24:47 -070075 'ln -sf _root_/repos _target_/repos',
76 'make prep',
77]
78
Zack Williams6b2fcf22021-09-14 06:50:44 -070079# don't include tags
80smv_tag_whitelist = None
81
Zack Williams76744322020-04-09 22:00:35 -070082# inlcude only the branches matching master and voltha-*
83smv_branch_whitelist = r'^(master|voltha-.*)$'
84
85# include all remote branches
86smv_remote_whitelist = r'^.*$'
87
Zack Williams071eda22019-05-15 18:19:51 -070088# Add any paths that contain templates here, relative to this directory.
89templates_path = ['_templates']
90
91# The suffix(es) of source filenames.
92# You can specify multiple suffix as a list of string:
93#
94# source_suffix = ['.rst', '.md']
95source_suffix = ['.rst', '.md']
96
97# The master toctree document.
98master_doc = 'index'
99
100# The language for content autogenerated by Sphinx. Refer to documentation
101# for a list of supported languages.
102#
103# This is also used if you do content translation via gettext catalogs.
104# Usually you set "language" from the command line for these cases.
105language = None
106
107# List of patterns, relative to source directory, that match files and
108# directories to ignore when looking for source files.
109# This pattern also affects html_static_path and html_extra_path.
110exclude_patterns = [
111 '*/LICENSE.md',
Matteo Scandoloef5d6f42020-07-27 16:46:38 -0700112 '*/RELEASE_NOTES.md',
Zack Williams071eda22019-05-15 18:19:51 -0700113 '*/vendor',
114 '.DS_Store',
115 'Thumbs.db',
116 '_build',
Zack Williams16042b62020-03-29 22:03:16 -0700117 'venv_docs',
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100118 'voltha-system-tests/vst_venv',
Zack Williams16042b62020-03-29 22:03:16 -0700119 'voltha-go/BUILD.md',
Andy Bavier39d67b12020-02-27 16:08:52 -0700120 'cord-tester/venv_cord',
121 'cord-tester/docs',
122 'cord-tester/src',
123 'cord-tester/README.md',
124 'cord-tester/cord-robot/README.rst',
Zack Williams16042b62020-03-29 22:03:16 -0700125 'openolt/agent/*',
Zack Williams071eda22019-05-15 18:19:51 -0700126 'repos',
127 'requirements.txt',
128 'bbsim/README.md',
Zack Williamsf2391542019-12-11 15:49:19 -0700129 'CODE_OF_CONDUCT.md',
130 '*/CODE_OF_CONDUCT.md',
Matteo Scandoloef5d6f42020-07-27 16:46:38 -0700131 'doc_venv/*'
Zack Williams071eda22019-05-15 18:19:51 -0700132]
133
134# The name of the Pygments (syntax highlighting) style to use.
135pygments_style = None
136
137# -- Options for HTML output -------------------------------------------------
138
139# The theme to use for HTML and HTML Help pages. See the documentation for
140# a list of builtin themes.
141#
142html_theme = 'sphinx_rtd_theme'
143
Zack Williams16042b62020-03-29 22:03:16 -0700144html_logo = '_static/voltha.svg'
145
146html_favicon = '_static/voltha-favicon-128.png'
147
Zack Williams071eda22019-05-15 18:19:51 -0700148# Theme options are theme-specific and customize the look and feel of a theme
149# further. For a list of options available for each theme, see the
150# documentation.
151#
Zack Williams16042b62020-03-29 22:03:16 -0700152html_theme_options = {
153 'logo_only': True
154}
Zack Williams071eda22019-05-15 18:19:51 -0700155
156# Add any paths that contain custom static files (such as style sheets) here,
157# relative to this directory. They are copied after the builtin static files,
158# so a file named "default.css" will overwrite the builtin "default.css".
159html_static_path = ['_static']
160
161# Custom sidebar templates, must be a dictionary that maps document names
162# to template names.
163#
164# The default sidebars (for documents that don't match any pattern) are
165# defined by theme itself. Builtin themes are using these templates by
166# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
167# 'searchbox.html']``.
168#
169# html_sidebars = {}
170
171
Zack Williams16042b62020-03-29 22:03:16 -0700172
Zack Williams071eda22019-05-15 18:19:51 -0700173# -- Options for HTMLHelp output ---------------------------------------------
174
175# Output file base name for HTML help builder.
176htmlhelp_basename = 'VOLTHADocs'
177
178
179# -- Options for LaTeX output ------------------------------------------------
180
181latex_elements = {
182 # The paper size ('letterpaper' or 'a4paper').
183 #
184 # 'papersize': 'letterpaper',
185
186 # The font size ('10pt', '11pt' or '12pt').
187 #
188 # 'pointsize': '10pt',
189
190 # Additional stuff for the LaTeX preamble.
191 #
192 # 'preamble': '',
193
194 # Latex figure (float) alignment
195 #
196 # 'figure_align': 'htbp',
197}
198
199# Grouping the document tree into LaTeX files. List of tuples
200# (source start file, target name, title,
201# author, documentclass [howto, manual, or own class]).
202latex_documents = [
203 (master_doc, 'VOLTHADocs.tex', u'VOLTHA Docs',
204 u'VOLTHA Team', 'manual'),
205]
206
207
208# -- Options for manual page output ------------------------------------------
209
210# One entry per manual page. List of tuples
211# (source start file, name, description, authors, manual section).
212man_pages = [
213 (master_doc, 'VOLTHA Docs', u'VOLTHA Docs',
214 [author], 1)
215]
216
217
218# -- Options for Texinfo output ----------------------------------------------
219
220# Grouping the document tree into Texinfo files. List of tuples
221# (source start file, target name, title, author,
222# dir menu entry, description, category)
223texinfo_documents = [
224 (master_doc, 'VOLTHA Docs', u'VOLTHA Docs',
225 author, 'VOLTHADocs', 'One line description of project.',
226 'Miscellaneous'),
227]
228
229
230# -- Options for Epub output -------------------------------------------------
231
232# Bibliographic Dublin Core info.
233epub_title = project
234
235# The unique identifier of the text. This can be a ISBN number
236# or the project homepage.
237#
238# epub_identifier = ''
239
240# A unique identification for the text.
241#
242# epub_uid = ''
243
244# A list of files that should not be packed into the epub file.
245epub_exclude_files = ['search.html']
246
247
248# -- Extension configuration -------------------------------------------------
249
250# blockdiag/etc. config
251
252rackdiag_antialias = True
253rackdiag_html_image_format = "SVG"
254rackdiag_fontpath = [
255 "_static/fonts/Inconsolata-Regular.ttf",
256 "_static/fonts/Inconsolata-Bold.ttf",
257]
258
259nwdiag_antialias = True
260nwdiag_html_image_format = "SVG"
261nwdiag_fontpath = [
262 "_static/fonts/Inconsolata-Regular.ttf",
263 "_static/fonts/Inconsolata-Bold.ttf",
264]
265
Joey Armstrongbbd71d62022-10-12 11:51:35 -0400266# -- Options for extlinks extension ------------------------------------------
267# ..seealso: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
268# 'vhc' : 'https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts',
269extlinks=\
270 {
271 'vol-jira' : ('https://jira.opencord.org/projects/VOL/issues/%s', 'jira::%s'),
272 'vol-ger' : ('https://gerrit.opencord.org/plugins/gitiles/%s', 'gerrit::%s'),
273 'vol-git' : ('https://github.com/opencord/%s', 'git::%s'),
274 }
275
Zack Williams071eda22019-05-15 18:19:51 -0700276# -- Options for todo extension ----------------------------------------------
277# If true, `todo` and `todoList` produce output, else they produce nothing.
278todo_include_todos = True
279
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100280# -- Options for linkcheck ---------------------------------------------------
281# The link checker strips off .md from links and then complains
Andrea Campanella8245ff52021-10-06 11:50:03 +0200282linkcheck_ignore = [r'https://github.com/opencord/voltctl/blob/master/LICENSE',
Zack Williams16042b62020-03-29 22:03:16 -0700283 r'https://github.com/ciena/kind-voltha#voltha-up-configuration-options',
284 r'https://www.sphinx-doc.org',
Andrea Campanella9f534c72021-03-19 18:44:27 +0100285 r'https://github.com/opencord/bbsim/blob/master/docs/source/DMI_Server_README',
Andrea Campanella8245ff52021-10-06 11:50:03 +0200286 r'https://github.com/opencord/voltha-helm-charts/blob/master/README'
Zack Williams16042b62020-03-29 22:03:16 -0700287 ]
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100288
Zack Williams071eda22019-05-15 18:19:51 -0700289# -- Configure recommonmark to use AutoStructify -----------------------------
290# Docs: https://recommonmark.readthedocs.io/en/latest/auto_structify.html
291
292import recommonmark
293from recommonmark.transform import AutoStructify
294
295github_doc_root = 'https://github.com/opencord/voltha-docs'
296
297def setup(app):
298
299 app.add_css_file('css/rtd_theme_mods.css')
300
301 app.add_config_value('recommonmark_config', {
302 'url_resolver': lambda url: github_doc_root + url,
303 'auto_toc_tree_section': 'Contents',
304 }, True)
305
306 app.add_transform(AutoStructify)