GeezerVison is showing github.com — sof-docs/conf.py at master · thesofproject/sof-docs

Expand file tree

conf.py

Copy path

More file actions

Latest commit

History

executable file

326 lines (268 loc) · 10.5 KB

conf.py

Copy path

File metadata and controls

executable file

326 lines (268 loc) · 10.5 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

# -*- coding: utf-8 -*-

# Project SOF documentation build configuration file, created by

# sphinx-quickstart on Wed Jan 10 20:51:29 2018.

# This file is execfile()d with the current directory set to its

# containing dir.

# Note that not all possible configuration values are present in this

# autogenerated file.

# All configuration values have a default; values that are commented out

# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,

# add these directories to sys.path here. If the directory is relative to the

# documentation root, use os.path.abspath to make it absolute, like shown here.

import os

import sys

sys.path.insert(0, os.path.abspath('.'))

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.

# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be

# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

# ones.

extensions = ['breathe', 'sphinx.ext.graphviz', 'sphinxcontrib.plantuml',

'sphinx.ext.todo', 'sphinx.ext.extlinks',

'sphinxcontrib.jquery',

'sphinx_copybutton',

'sphinx_tabs.tabs'

]

# Copybutton configuration: strip console prompts ($, #, >>>) and handle continuation lines

copybutton_prompt_text = r">>> |\.\.\. |\$ |# |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "

copybutton_prompt_is_regexp = True

copybutton_line_continuation_character = "\\"

# Sphinx-tabs configuration

sphinx_tabs_disable_tab_closing = True

sphinx_tabs_disable_css_loading = True

# Suppress duplicate declaration warnings from anonymous structs in Breathe

suppress_warnings = ['duplicate_declaration.c']

try:

import myst_parser

extensions.append('myst_parser')

except ImportError:

pass

graphviz_output_format='svg'

graphviz_dot_args=[

'-Nfontname=verdana',

'-Gfontname=verdana',

'-Efontname=verdana']

plantuml = 'java -jar ' + os.path.join(os.path.abspath('.'), 'scripts/plantuml.jar') \

+ ' -config ' + os.path.join(os.path.abspath('.'), 'scripts/plantuml.cfg')

# More than half of the time building from scratch is consumed by the

# sphinx extension "breathe" that converts doxygen XML. Most of the rest

# is consumed by plantUML here. So you can set the variable below to

# 'none' for an _almost instant_ sphinx build! (with zero UML diagram

# and no doxygen). 'none' requires sphinxcontrib.plantuml>=0.11 but

# pre-0.11 errors can be ignored. (of course don't disable UML when

# you're touching UML stuff)

plantuml_output_format = 'svg'

# Add any paths that contain templates here, relative to this directory.

templates_path = ['_templates']

# Fixes "WARNING: Error when parsing function declaration."

c_id_attributes = ["__sparse_cache", "__syscall", "__packed", "__aligned", "__kernel", "__user", "__section"]

cpp_id_attributes = c_id_attributes

# cpp_paren_attributes = ["_ALIAS_OF", "__printf_like"]

breathe_domain_by_extension = {"h": "c"}

# The suffix(es) of source filenames.

# You can specify multiple suffix as a list of string:

# source_suffix = ['.rst', '.md']

source_suffix = '.rst'

# The master toctree document.

master_doc = 'index'

# General information about the project.

project = u'SOF Project'

author = u'SOF Project developers'

# The version info for the project you're documenting, acts as replacement for

# |version| and |release|, also used in various other places throughout the

# built documents.

version = release = "2.11.0"

# The short X.Y version.

# version = u'0.1'

# The full version, including alpha/beta/rc tags.

# release = u'0.1'

# The language for content autogenerated by Sphinx. Refer to documentation

# for a list of supported languages.

# This is also used if you do content translation via gettext catalogs.

# Usually you set "language" from the command line for these cases.

language = 'en'

# List of patterns, relative to source directory, that match files and

# directories to ignore when looking for source files.

# This patterns also effect to html_static_path and html_extra_path

# Note: a virtualenv created inside this source tree (.venv, venv, env, ...)

# would otherwise be scanned by Sphinx and flood the build with warnings

# about .rst files shipped in installed packages.

exclude_patterns = [

'_build',

'.tox',

'.venv*',

'venv',

'env',

'README.md',

'scripts/*.md',

'sof',

'sof/**',

'_deps',

'_deps/**',

'_build_doxy',

'_build_doxy/**',

]

# The name of the Pygments (syntax highlighting) style to use.

pygments_style = 'sphinx'

# If true, `todo` and `todoList` produce output, else they produce nothing.

todo_include_todos =False

# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for

# a list of builtin themes.

try:

import pydata_sphinx_theme

html_theme = "pydata_sphinx_theme"

html_theme_options = {

"logo": {

"link": "introduction/index",

"github_url": "https://github.com/thesofproject/sof",

"external_links": [

{"name": "SOF Project Website", "url": "https://sofproject.org"}

"navbar_end": ["theme-switcher", "navbar-icon-links"],

}

except ImportError:

try:

import sphinx_rtd_theme

except ImportError:

html_theme = 'alabaster'

# This is required for the alabaster theme

# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars

html_sidebars = {

'**': [

'relations.html', # needs 'show_related': True theme option to display

'searchbox.html',

]

}

sys.stderr.write('Warning: sphinx_rtd_theme missing. Use pip to install it.\n')

else:

html_theme = "sphinx_rtd_theme"

html_theme_options = {

'canonical_url': '',

'analytics_id': 'GTM-M4BL5NF',

'logo_only': False,

'prev_next_buttons_location': 'None',

# Toc options

'collapse_navigation': False,

'sticky_navigation': True,

'navigation_depth': 4,

}

# Here's where we (manually) list the document versions maintained on

# the published doc website. On a daily basis we publish to the

# /latest folder but when releases are made, we publish to a /<relnum>

# folder (specified via RELEASE=name on the make command).

if tags.has('release'):

current_version = version

else:

version = current_version = "latest"

html_context = {

'current_version': current_version,

'versions': ( ("latest", "/latest/"),

# ("0.1-rc4", "/0.1-rc4/"),

)

}

# Theme options are theme-specific and customize the look and feel of a theme

# further. For a list of options available for each theme, see the

# documentation.

# html_theme_options = {}

html_logo = 'images/logo_sof_white_200w.png'

html_favicon = 'images/sof-favicon.svg'

numfig = True

#numfig_secnum_depth = (2)

numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', 'code-block': 'Code Block %s'}

SOF_GIT = 'https://github.com/thesofproject'

# "/sof/tree/branch/dir" is for directories and "/sof/blob/branch/file" is

# for files. Fortunately github automatically redirects one to the other

# as required.

extlinks = {

'git-sof-mainline':

(SOF_GIT + '/sof/tree/master/%s', None),

'git-sof-docs-mainline':

(SOF_GIT + '/sof-docs/tree/master/%s', None),

'git-sof-kconfig':

(SOF_GIT + '/kconfig/tree/master/%s', None),

'git-alsa':

('https://git.alsa-project.org/?p=%s.git', None),

}

# Add any paths that contain custom static files (such as style sheets) here,

# relative to this directory. They are copied after the builtin static files,

# so a file named "default.css" will overwrite the builtin "default.css".

html_static_path = ['static']

def setup(app):

import logging

from sphinx.util.logging import NAMESPACE, WarningStreamHandler

class BreatheAnonymousUnionFilter(logging.Filter):

def filter(self, record):

msg = record.getMessage()

# Suppress breathe limitation parsing anonymous union/struct members (e.g. bind_info, dp_schedule)

if "bind_info" in msg or "Expected identifier in nested name" in msg or "Duplicate C declaration" in msg:

return False

return True

logger = logging.getLogger(NAMESPACE)

for handler in logger.handlers:

if isinstance(handler, WarningStreamHandler):

handler.filters.insert(0, BreatheAnonymousUnionFilter())

# add_stylesheet() was renamed to add_css_file() in sphinx 1.8 released

# in September 2018. add_stylesheet() will be removed in sphinx 4.0

try:

app.add_css_file('sof-custom.css')

except AttributeError:

app.add_stylesheet('sof-custom.css')

try:

app.add_js_file('sof-custom.js')

except AttributeError:

app.add_javascript('sof-custom.js')

# Custom sidebar templates, must be a dictionary that maps document names

# to template names.

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.

html_show_sphinx = False

# If true, links to the reST sources are added to the pages.

html_show_sourcelink = False

# If not '', a 'Last updated on:' timestamp is inserted at every page

# bottom,

# using the given strftime format.

html_last_updated_fmt = '%b %d, %Y'

# -- Options for HTMLHelp output ------------------------------------------

rst_epilog = """

.. include:: /substitutions.txt

"""

# Look for Doxygen XML path if not already provided or overridden

_breathe_xml_candidates = [

os.path.join(os.environ['SOF_DOC_BUILD'], 'doxygen/xml') if os.environ.get('SOF_DOC_BUILD') else None,

os.path.join(os.environ['SOF_ROOT'], 'build_doxygen/doxygen/xml') if os.environ.get('SOF_ROOT') else None,

os.path.abspath('../sof-dox-work/build_doxygen/doxygen/xml'),

os.path.abspath('../sof/build_doxygen/doxygen/xml'),

os.path.abspath('../sof-tgl/sof/build_doxygen/doxygen/xml'),

os.path.abspath('../sof/doc/doxygen/xml'),

]

_breathe_xml_path = None

for _cand in _breathe_xml_candidates:

if _cand and os.path.isdir(_cand):

_breathe_xml_path = _cand

break

breathe_projects = {

"SOF Project" : _breathe_xml_path or "../sof/doc/doxygen/xml",

}

breathe_default_project = "SOF Project"

breathe_default_members = ('members', 'undoc-members', 'content-only')

try:

if "tox" not in exclude_patterns:

exclude_patterns.append(".tox")

except:

exclude_patterns = [".tox"]