Configuration

lfdocs-conf reads aggregates configurations from sources to determine the effective configuration to build Sphinx. Precedence for configuration is as follows:

  1. project/conf.py
  2. project/conf.yaml
  3. docs_conf/defaults/{project_cfg}.yaml
  4. docs_conf/defaults/default.yaml
  5. 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.

  1. conf.yaml (preferred)
  2. 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
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.