blob: cfd7dd4b598613716aebca794c1cce16d2989dd5 [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
Joey Armstrong56334fc2023-01-15 22:53:19 -050015##-------------------##
16##---] IMPORTS [---##
17##-------------------##
Zack Williams16042b62020-03-29 22:03:16 -070018import os
Joey Armstrong56334fc2023-01-15 22:53:19 -050019import sys
20from pathlib import Path
Zack Williams16042b62020-03-29 22:03:16 -070021
Joey Armstrong56334fc2023-01-15 22:53:19 -050022if True:
23 pwd = Path(__file__).parent.as_posix()
24 sys.path.append(pwd)
25
26# -----------------------------------------------------------------------
27# -----------------------------------------------------------------------
Zack Williams16042b62020-03-29 22:03:16 -070028def get_version():
29 with open("VERSION") as f:
30 return f.read().strip()
31
Zack Williams071eda22019-05-15 18:19:51 -070032# -- Project information -----------------------------------------------------
33
34project = u'VOLTHA Docs'
Joey Armstrong56334fc2023-01-15 22:53:19 -050035copyright = u'Copyright 2019-2023 Open Networking Foundation (ONF) and the ONF Contributors'
Zack Williams071eda22019-05-15 18:19:51 -070036author = u'VOLTHA Contributors'
37
38# The short X.Y version
Zack Williams16042b62020-03-29 22:03:16 -070039version = get_version()
Zack Williams071eda22019-05-15 18:19:51 -070040# The full version, including alpha/beta/rc tags
Zack Williams88df4742019-12-20 08:24:47 -070041release = version
Zack Williams071eda22019-05-15 18:19:51 -070042
43# -- General configuration ---------------------------------------------------
44
45# If your documentation needs a minimal Sphinx version, state it here.
46#
47# needs_sphinx = '1.0'
48
49# make all warnings errors
50warning_is_error = True
51
52# Add any Sphinx extension module names here, as strings. They can be
53# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
54# ones.
55extensions = [
56 'recommonmark',
57 'sphinx.ext.coverage',
Joey Armstrongbbd71d62022-10-12 11:51:35 -040058 'sphinx.ext.extlinks',
Zack Williams071eda22019-05-15 18:19:51 -070059 'sphinx.ext.graphviz',
60 'sphinx.ext.ifconfig',
61 'sphinx.ext.mathjax',
62 'sphinx.ext.todo',
Zack Williamsc6460c22019-12-18 14:54:43 -070063 'sphinxcontrib.spelling',
Zack Williams16042b62020-03-29 22:03:16 -070064 "sphinx_multiversion",
Matteo Scandoloef5d6f42020-07-27 16:46:38 -070065 "sphinx.ext.intersphinx",
Andrea Campanellac18d1182021-09-10 12:01:38 +020066 "sphinxcontrib.openapi",
Zack Williams071eda22019-05-15 18:19:51 -070067]
68
69# API documentation
70# https://github.com/rtfd/sphinx-autoapi
71# https://sphinx-autoapi.readthedocs.io
72# autoapi_type = 'go'
73# autoapi_dirs = [
74# 'voltha-go/cli/util',
75# 'voltha-go/rw_core/config',
76# 'voltha-go/rw_core/core',
77# 'voltha-go/rw_core/graph',
78# 'voltha-go/rw_core/utils',
79# ]
80
Zack Williamsc6460c22019-12-18 14:54:43 -070081# Text files with lists of words that shouldn't fail the spellchecker:
82spelling_word_list_filename=['dict.txt', ]
83
Joey Armstrongbbd71d62022-10-12 11:51:35 -040084#sphinx-multiversion prep, run in each versioned source directory
Zack Williams16042b62020-03-29 22:03:16 -070085prep_commands = [
Zack Williams88df4742019-12-20 08:24:47 -070086 'ln -sf _root_/repos _target_/repos',
87 'make prep',
88]
89
Zack Williams6b2fcf22021-09-14 06:50:44 -070090# don't include tags
91smv_tag_whitelist = None
92
Zack Williams76744322020-04-09 22:00:35 -070093# inlcude only the branches matching master and voltha-*
94smv_branch_whitelist = r'^(master|voltha-.*)$'
95
96# include all remote branches
97smv_remote_whitelist = r'^.*$'
98
Zack Williams071eda22019-05-15 18:19:51 -070099# Add any paths that contain templates here, relative to this directory.
100templates_path = ['_templates']
101
102# The suffix(es) of source filenames.
103# You can specify multiple suffix as a list of string:
104#
105# source_suffix = ['.rst', '.md']
106source_suffix = ['.rst', '.md']
107
108# The master toctree document.
109master_doc = 'index'
110
111# The language for content autogenerated by Sphinx. Refer to documentation
112# for a list of supported languages.
113#
114# This is also used if you do content translation via gettext catalogs.
115# Usually you set "language" from the command line for these cases.
116language = None
117
118# List of patterns, relative to source directory, that match files and
119# directories to ignore when looking for source files.
120# This pattern also affects html_static_path and html_extra_path.
121exclude_patterns = [
122 '*/LICENSE.md',
Matteo Scandoloef5d6f42020-07-27 16:46:38 -0700123 '*/RELEASE_NOTES.md',
Zack Williams071eda22019-05-15 18:19:51 -0700124 '*/vendor',
125 '.DS_Store',
126 'Thumbs.db',
127 '_build',
Zack Williams16042b62020-03-29 22:03:16 -0700128 'voltha-go/BUILD.md',
Andy Bavier39d67b12020-02-27 16:08:52 -0700129 'cord-tester/venv_cord',
130 'cord-tester/docs',
131 'cord-tester/src',
132 'cord-tester/README.md',
133 'cord-tester/cord-robot/README.rst',
Zack Williams16042b62020-03-29 22:03:16 -0700134 'openolt/agent/*',
Zack Williams071eda22019-05-15 18:19:51 -0700135 'repos',
136 'requirements.txt',
137 'bbsim/README.md',
Zack Williamsf2391542019-12-11 15:49:19 -0700138 'CODE_OF_CONDUCT.md',
139 '*/CODE_OF_CONDUCT.md',
Joey Armstronga62c74a2022-11-23 13:16:34 -0500140# Ignore all:
141 '**/__pycache__', # generated - faster traversal
142# Revisit: one directory pattern is sufficient.
143 '**/doc_venv',
144 '**/venv_docs',
145 '**/virtualenv',
146 '**/vst_venv',
Zack Williams071eda22019-05-15 18:19:51 -0700147]
148
149# The name of the Pygments (syntax highlighting) style to use.
150pygments_style = None
151
152# -- Options for HTML output -------------------------------------------------
153
154# The theme to use for HTML and HTML Help pages. See the documentation for
155# a list of builtin themes.
156#
157html_theme = 'sphinx_rtd_theme'
158
Zack Williams16042b62020-03-29 22:03:16 -0700159html_logo = '_static/voltha.svg'
160
161html_favicon = '_static/voltha-favicon-128.png'
162
Zack Williams071eda22019-05-15 18:19:51 -0700163# Theme options are theme-specific and customize the look and feel of a theme
164# further. For a list of options available for each theme, see the
165# documentation.
166#
Zack Williams16042b62020-03-29 22:03:16 -0700167html_theme_options = {
168 'logo_only': True
169}
Zack Williams071eda22019-05-15 18:19:51 -0700170
171# Add any paths that contain custom static files (such as style sheets) here,
172# relative to this directory. They are copied after the builtin static files,
173# so a file named "default.css" will overwrite the builtin "default.css".
174html_static_path = ['_static']
175
176# Custom sidebar templates, must be a dictionary that maps document names
177# to template names.
178#
179# The default sidebars (for documents that don't match any pattern) are
180# defined by theme itself. Builtin themes are using these templates by
181# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
182# 'searchbox.html']``.
183#
184# html_sidebars = {}
185
186
Zack Williams16042b62020-03-29 22:03:16 -0700187
Zack Williams071eda22019-05-15 18:19:51 -0700188# -- Options for HTMLHelp output ---------------------------------------------
189
190# Output file base name for HTML help builder.
191htmlhelp_basename = 'VOLTHADocs'
192
193
194# -- Options for LaTeX output ------------------------------------------------
195
196latex_elements = {
197 # The paper size ('letterpaper' or 'a4paper').
198 #
199 # 'papersize': 'letterpaper',
200
201 # The font size ('10pt', '11pt' or '12pt').
202 #
203 # 'pointsize': '10pt',
204
205 # Additional stuff for the LaTeX preamble.
206 #
207 # 'preamble': '',
208
209 # Latex figure (float) alignment
210 #
211 # 'figure_align': 'htbp',
212}
213
214# Grouping the document tree into LaTeX files. List of tuples
215# (source start file, target name, title,
216# author, documentclass [howto, manual, or own class]).
217latex_documents = [
218 (master_doc, 'VOLTHADocs.tex', u'VOLTHA Docs',
219 u'VOLTHA Team', 'manual'),
220]
221
222
223# -- Options for manual page output ------------------------------------------
224
225# One entry per manual page. List of tuples
226# (source start file, name, description, authors, manual section).
227man_pages = [
228 (master_doc, 'VOLTHA Docs', u'VOLTHA Docs',
229 [author], 1)
230]
231
232
233# -- Options for Texinfo output ----------------------------------------------
234
235# Grouping the document tree into Texinfo files. List of tuples
236# (source start file, target name, title, author,
237# dir menu entry, description, category)
238texinfo_documents = [
239 (master_doc, 'VOLTHA Docs', u'VOLTHA Docs',
240 author, 'VOLTHADocs', 'One line description of project.',
241 'Miscellaneous'),
242]
243
244
245# -- Options for Epub output -------------------------------------------------
246
247# Bibliographic Dublin Core info.
248epub_title = project
249
250# The unique identifier of the text. This can be a ISBN number
251# or the project homepage.
252#
253# epub_identifier = ''
254
255# A unique identification for the text.
256#
257# epub_uid = ''
258
259# A list of files that should not be packed into the epub file.
260epub_exclude_files = ['search.html']
261
262
263# -- Extension configuration -------------------------------------------------
264
265# blockdiag/etc. config
266
267rackdiag_antialias = True
268rackdiag_html_image_format = "SVG"
269rackdiag_fontpath = [
270 "_static/fonts/Inconsolata-Regular.ttf",
271 "_static/fonts/Inconsolata-Bold.ttf",
272]
273
274nwdiag_antialias = True
275nwdiag_html_image_format = "SVG"
276nwdiag_fontpath = [
277 "_static/fonts/Inconsolata-Regular.ttf",
278 "_static/fonts/Inconsolata-Bold.ttf",
279]
280
Joey Armstrongbbd71d62022-10-12 11:51:35 -0400281# -- Options for extlinks extension ------------------------------------------
282# ..seealso: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
283# 'vhc' : 'https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts',
Joey Armstrong56334fc2023-01-15 22:53:19 -0500284
Joey Armstrongbbd71d62022-10-12 11:51:35 -0400285extlinks=\
286 {
287 'vol-jira' : ('https://jira.opencord.org/projects/VOL/issues/%s', 'jira::%s'),
Joey Armstrong56334fc2023-01-15 22:53:19 -0500288 # macros for gerrit or github URL construction
289 'repo' : ('https://github.com/opencord/%s', 'repo::%s'),
Joey Armstrongbbd71d62022-10-12 11:51:35 -0400290 'vol-ger' : ('https://gerrit.opencord.org/plugins/gitiles/%s', 'gerrit::%s'),
291 'vol-git' : ('https://github.com/opencord/%s', 'git::%s'),
292 }
293
Joey Armstrong2a687952023-02-01 13:10:12 -0500294# -- Options for inlining a constant value -----------------------------------
295# NOTE: rst_prolog will affect every file in the repository.
296# Use per-file substitution to limit scope:
297# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
298# rst_prolog = """
299# .. |voltha-latest| replace:: voltha-2.11
300# """
301
Zack Williams071eda22019-05-15 18:19:51 -0700302# -- Options for todo extension ----------------------------------------------
303# If true, `todo` and `todoList` produce output, else they produce nothing.
304todo_include_todos = True
305
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100306# -- Options for linkcheck ---------------------------------------------------
307# The link checker strips off .md from links and then complains
Joey Armstrong36592e32022-11-28 09:00:28 -0500308linkcheck_ignore=\
309 [
310 r'https://github.com/opencord/voltctl/blob/master/LICENSE',
311 r'https://github.com/ciena/kind-voltha#voltha-up-configuration-options',
312 r'https://www.sphinx-doc.org',
313 r'https://github.com/opencord/bbsim/blob/master/docs/source/DMI_Server_README',
314 r'https://github.com/opencord/voltha-helm-charts/blob/master/README',
315 r'https://github.com/atomix/atomix/releases/tag/atomix-3.1.9',
316 r'https://github.com/atomix/atomix/releases/tag/atomix-3.1.8',
Joey Armstrongf88b7382022-12-02 15:04:21 -0500317 #
318 r'../release_notes/voltha_2.2.html',
319 r'../release_notes/voltha_2.3.html',
320 r'../release_notes/voltha_2.4.html',
321 r'../release_notes/voltha_2.5.html',
322 r'../release_notes/voltha_2.6.html',
323 r'../release_notes/voltha_2.7.html',
324 r'../release_notes/voltha_2.8.html',
325 r'../release_notes/voltha_2.9.html',
326 r'../release_notes/voltha_2.10.html',
Joey Armstrong4044ed92022-12-21 19:01:49 -0500327 r'../release_notes/voltha_2.11.html',
Joey Armstrong7d32cbe2023-06-02 14:30:19 -0400328 r'../release_notes/voltha_2.12.html',
Joey Armstronga4d27232022-12-29 08:50:02 -0500329 #
330 r'../voltha-helm-charts/README.html',
Joey Armstrong36592e32022-11-28 09:00:28 -0500331 ]
Andrea Campanella92bd59b2020-01-30 17:26:32 +0100332
Zack Williams071eda22019-05-15 18:19:51 -0700333# -- Configure recommonmark to use AutoStructify -----------------------------
334# Docs: https://recommonmark.readthedocs.io/en/latest/auto_structify.html
335
336import recommonmark
337from recommonmark.transform import AutoStructify
338
339github_doc_root = 'https://github.com/opencord/voltha-docs'
340
341def setup(app):
342
343 app.add_css_file('css/rtd_theme_mods.css')
344
345 app.add_config_value('recommonmark_config', {
346 'url_resolver': lambda url: github_doc_root + url,
347 'auto_toc_tree_section': 'Contents',
348 }, True)
349
350 app.add_transform(AutoStructify)