Configuration¶
lfdocs-conf reads aggregates configurations from sources to determine the effective configuration to build Sphinx. Precedence for configuration is as follows:
project/conf.py
project/conf.yaml
docs_conf/defaults/{project_cfg}.yaml
docs_conf/defaults/default.yaml
docs_conf/__init__.py
Typically {project_cfg}.yaml provides a common theme across related projects. For example all subprojects within the OpenDaylight project share the common docs_conf/defaults/opendaylight.yaml. All fields provided by defaults are overidable via one of 2 ways.
conf.yaml (preferred)
conf.py
conf.yaml¶
In most cases projects should use conf.yaml to configure settings. This file should at least configure the “project_cfg” setting which will pull the appropriate defaults configuration for their top level project to ensure a consistent theme across all subprojects within a project. Settings here can override settings that you would like different from the project defaults.
Commonly used fields are “project”, “version”, and “author”.
---
project_cfg: opendaylight
project: NetVirt
release: 1.2.3
version: 1.2.3
author: OpenDaylight Project
copyright: 2018, OpenDaylight Project a Series of LF Projects, LLC
needs_sphinx: "1.6.5"
extensions:
- sphinx.ext.autodoc
- sphinx.ext.doctest
- sphinx.ext.intersphinx
- sphinx.ext.todo
- sphinx.ext.coverage
- sphinx.ext.viewcode
exclude_patterns:
- .DS_Store
- _build
- Thumbs.db
- .tox
todo_include_todos: false
html_logo: _static/logo.png
html_theme: bootstrap
html_theme_options:
bootswatch_theme: cerulean
navbar_sidebarrel: false
source_link_position: footer
conf.py¶
If conf.yaml does not support a Sphinx configuration you need or you have more complex configuration needs where Python code might be useful then you can use conf.py. This file supports the full configuration of Sphinx conf.py.