ceph/doc/conf.py

   1 import fileinput
   2 import glob
   3 import logging
   4 import os
   5 import shutil
   6 import sys
   7 import yaml
   8 import sphinx.util
   9
  10
  11 top_level = \
  12     os.path.dirname(
  13         os.path.dirname(
  14             os.path.abspath(__file__)))
  15
  16 pybind_rgw_mod = __import__('rgw', globals(), locals(), [], 0)
  17 sys.modules['pybind_rgw_mod'] = pybind_rgw_mod
  18
  19
  20 def parse_ceph_release():
  21     with open(os.path.join(top_level, 'src/ceph_release')) as f:
  22         lines = f.readlines()
  23         assert(len(lines) == 3)
  24         # 16, pacific, dev
  25         version, codename, status = [line.strip() for line in lines]
  26         return version, codename, status
  27
  28
  29 def latest_stable_release():
  30     with open(os.path.join(top_level, 'doc/releases/releases.yml')) as input:
  31         releases = yaml.safe_load(input)['releases']
  32         # get the first release
  33         return next(iter(releases.keys()))
  34
  35
  36 def is_release_eol(codename):
  37     with open(os.path.join(top_level, 'doc/releases/releases.yml')) as input:
  38         releases = yaml.safe_load(input)['releases']
  39         return 'actual_eol' in releases.get(codename, {})
  40
  41
  42 # project information
  43 project = 'Ceph'
  44 copyright = ('2016, Ceph authors and contributors. '
  45              'Licensed under Creative Commons Attribution Share Alike 3.0 '
  46              '(CC-BY-SA-3.0)')
  47 version, codename, release = parse_ceph_release()
  48 pygments_style = 'sphinx'
  49
  50 # HTML output options
  51 html_theme = 'ceph'
  52 html_theme_options = {
  53     'logo_only': True,
  54     'display_version': False,
  55     'prev_next_buttons_location': 'bottom',
  56     'style_external_links': False,
  57     'vcs_pageview_mode': 'edit',
  58     'style_nav_header_background': '#eee',
  59     # Toc options
  60     'collapse_navigation': True,
  61     'sticky_navigation': True,
  62     'navigation_depth': 4,
  63     'includehidden': True,
  64     'titles_only': False
  65 }
  66 html_theme_path = ['_themes']
  67 html_title = "Ceph Documentation"
  68 html_logo = 'logo.png'
  69 html_context = {'is_release_eol': is_release_eol(codename)}
  70 html_favicon = 'favicon.ico'
  71 html_show_sphinx = False
  72 html_static_path = ["_static"]
  73 html_sidebars = {
  74     '**': ['smarttoc.html', 'searchbox.html']
  75     }
  76
  77 html_css_files = ['css/custom.css']
  78
  79 # general configuration
  80 templates_path = ['_templates']
  81 source_suffix = '.rst'
  82 exclude_patterns = ['**/.#*',
  83                     '**/*~',
  84                     'start/quick-common.rst',
  85                     '**/*.inc.rst']
  86 if tags.has('man'):             # noqa: F821
  87     master_doc = 'man_index'
  88     exclude_patterns += ['index.rst',
  89                          'architecture.rst',
  90                          'glossary.rst',
  91                          'release*.rst',
  92                          'api/*',
  93                          'cephadm/*',
  94                          'cephfs/*',
  95                          'dev/*',
  96                          'governance.rst',
  97                          'foundation.rst',
  98                          'install/*',
  99                          'mon/*',
 100                          'rados/*',
 101                          'mgr/*',
 102                          'ceph-volume/*',
 103                          'radosgw/*',
 104                          'rbd/*',
 105                          'start/*',
 106                          'releases/*']
 107 else:
 108     master_doc = 'index'
 109     exclude_patterns += ['man_index.rst']
 110
 111 build_with_rtd = os.environ.get('READTHEDOCS') == 'True'
 112
 113 sys.path.insert(0, os.path.abspath('_ext'))
 114
 115 smartquotes_action = "qe"
 116
 117 extensions = [
 118     'sphinx.ext.autodoc',
 119     'sphinx.ext.graphviz',
 120     'sphinx.ext.mathjax',
 121     'sphinx.ext.todo',
 122     'sphinx-prompt',
 123     'sphinx_autodoc_typehints',
 124     'sphinx_substitution_extensions',
 125     'breathe',
 126     'ceph_commands',
 127     'ceph_releases',
 128     'ceph_confval',
 129     'sphinxcontrib.mermaid',
 130     'sphinxcontrib.openapi',
 131     'sphinxcontrib.seqdiag',
 132     ]
 133
 134 ditaa = shutil.which("ditaa")
 135 if ditaa is not None:
 136     # in case we don't have binfmt_misc enabled or jar is not registered
 137     ditaa_args = ['-jar', ditaa]
 138     ditaa = 'java'
 139     extensions += ['sphinxcontrib.ditaa']
 140 else:
 141     extensions += ['plantweb.directive']
 142     plantweb_defaults = {
 143         'engine': 'ditaa'
 144     }
 145
 146 if build_with_rtd:
 147     extensions += ['sphinx_search.extension']
 148
 149 # sphinx.ext.todo options
 150 todo_include_todos = True
 151
 152 # sphinx_substitution_extensions options
 153 rst_prolog = f"""
 154 .. |stable-release| replace:: {latest_stable_release()}
 155 """
 156
 157 # breath options
 158 breathe_default_project = "Ceph"
 159 # see $(top_srcdir)/Doxyfile
 160
 161 breathe_build_directory = os.path.join(top_level, "build-doc")
 162 breathe_projects = {"Ceph": os.path.join(top_level, breathe_build_directory)}
 163 breathe_projects_source = {
 164     "Ceph": (os.path.join(top_level, "src/include/rados"),
 165              ["rados_types.h", "librados.h"])
 166 }
 167 breathe_domain_by_extension = {'py': 'py',
 168                                'c': 'c', 'h': 'c',
 169                                'cc': 'cxx', 'hpp': 'cxx'}
 170 breathe_doxygen_config_options = {
 171     'EXPAND_ONLY_PREDEF': 'YES',
 172     'MACRO_EXPANSION': 'YES',
 173     'PREDEFINED': 'CEPH_RADOS_API= ',
 174     'WARN_IF_UNDOCUMENTED': 'NO',
 175 }
 176
 177 # graphviz options
 178 graphviz_output_format = 'svg'
 179
 180 def generate_state_diagram(input_paths, output_path):
 181     sys.path.append(os.path.join(top_level, 'doc', 'scripts'))
 182     from gen_state_diagram import do_filter, StateMachineRenderer
 183     inputs = [os.path.join(top_level, fn) for fn in input_paths]
 184     output = os.path.join(top_level, output_path)
 185
 186     def process(app):
 187         with fileinput.input(files=inputs) as f:
 188             input = do_filter(f)
 189             render = StateMachineRenderer()
 190             render.read_input(input)
 191             with open(output, 'w') as dot_output:
 192                 render.emit_dot(dot_output)
 193
 194     return process
 195
 196
 197 # mocking ceph_module offered by ceph-mgr. `ceph_module` is required by
 198 # mgr.mgr_module
 199 class Dummy(object):
 200     def __getattr__(self, _):
 201         return lambda *args, **kwargs: None
 202
 203
 204 class Mock(object):
 205     __all__ = []
 206
 207     def __init__(self, *args, **kwargs):
 208         pass
 209
 210     def __call__(self, *args, **kwargs):
 211         return Mock()
 212
 213     @classmethod
 214     def __getattr__(cls, name):
 215         mock = type(name, (Dummy,), {})
 216         mock.__module__ = __name__
 217         return mock
 218
 219
 220 # autodoc options
 221 sys.modules['ceph_module'] = Mock()
 222
 223 if build_with_rtd:
 224     autodoc_mock_imports = ['ceph']
 225     pybinds = ['pybind/mgr',
 226                'python-common']
 227 else:
 228     pybinds = ['pybind',
 229                'pybind/mgr',
 230                'python-common']
 231
 232 for c in pybinds:
 233     pybind = os.path.join(top_level, 'src', c)
 234     if pybind not in sys.path:
 235         sys.path.insert(0, pybind)
 236
 237 # openapi
 238 openapi_logger = sphinx.util.logging.getLogger('sphinxcontrib.openapi.openapi30')
 239 openapi_logger.setLevel(logging.WARNING)
 240
 241 # seqdiag
 242 seqdiag_antialias = True
 243 seqdiag_html_image_format = 'SVG'
 244
 245 # ceph_confval
 246 ceph_confval_imports = glob.glob(os.path.join(top_level,
 247                                               'src/common/options',
 248                                               '*.yaml.in'))
 249 ceph_confval_mgr_module_path = 'src/pybind/mgr'
 250 ceph_confval_mgr_python_path = 'src/pybind'
 251
 252 # handles edit-on-github and old version warning display
 253 def setup(app):
 254     if ditaa is None:
 255         # add "ditaa" as an alias of "diagram"
 256         from plantweb.directive import DiagramDirective
 257         app.add_directive('ditaa', DiagramDirective)
 258     app.connect('builder-inited',
 259                 generate_state_diagram(['src/osd/PeeringState.h',
 260                                         'src/osd/PeeringState.cc'],
 261                                        'doc/dev/peering_graph.generated.dot'))