doc/conf: re-group configurations

for better readability.

see also https://www.sphinx-doc.org/en/master/usage/configuration.html

Signed-off-by: Kefu Chai <kchai@redhat.com>

diff --git a/doc/conf.py b/doc/conf.py
index 87a26c77f4e393b39fa7a017c7e82710ed2fbc7f..31ea852a3422d1bf10342e47e7681abb8b00387a 100644 (file)
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -3,16 +3,32 @@ import shutil
 import sys
 import os
 
+# project information
 project = 'Ceph'
 copyright = ('2016, Ceph authors and contributors. '
              'Licensed under Creative Commons Attribution Share Alike 3.0 '
              '(CC-BY-SA-3.0)')
 version = 'dev'
 release = 'dev'
+pygments_style = 'sphinx'
+
+# HTML output options
+html_theme = 'ceph'
+html_theme_path = ['_themes']
+html_title = "Ceph Documentation"
+html_logo = 'logo.png'
+html_favicon = 'favicon.ico'
+html_show_sphinx = False
+html_static_path = ["_static"]
+html_sidebars = {
+    '**': ['smarttoc.html', 'searchbox.html']
+    }
 
+html_css_files = ['css/custom.css']
+
+# general configuration
 templates_path = ['_templates']
 source_suffix = '.rst'
-master_doc = 'index'
 exclude_patterns = ['**/.#*',
                     '**/*~',
                     'start/quick-common.rst',
@@ -39,23 +55,15 @@ if tags.has('man'):             # noqa: F821
                          'start/*',
                          'releases/*']
 else:
+    master_doc = 'index'
     exclude_patterns += ['man_index.rst']
 
-pygments_style = 'sphinx'
+build_with_rtd = os.environ.get('READTHEDOCS') == 'True'
+
+if build_with_rtd:
+    exclude_patterns += ['**/api/*',
+                         '**/api.rst']
 
-html_theme = 'ceph'
-html_theme_path = ['_themes']
-html_title = "Ceph Documentation"
-html_logo = 'logo.png'
-html_favicon = 'favicon.ico'
-html_show_sphinx = False
-html_static_path = ["_static"]
-html_sidebars = {
-    '**': ['smarttoc.html', 'searchbox.html'],
-    }
-html_css_files = [
-    'css/custom.css',
-]
 sys.path.insert(0, os.path.abspath('_ext'))
 
 extensions = [
@@ -81,14 +89,13 @@ else:
         'engine': 'ditaa'
     }
 
-build_with_rtd = os.environ.get('READTHEDOCS') == 'True'
 if build_with_rtd:
     extensions += ['sphinx_search.extension']
 
-# sphinx.ext.todo
+# sphinx.ext.todo options
 todo_include_todos = True
 
-# sphinx_substitution_extensions
+# sphinx_substitution_extensions options
 # TODO: read from doc/releases/releases.yml
 rst_prolog = """
 .. |stable-release| replace:: octopus
@@ -100,6 +107,7 @@ top_level = os.path.dirname(
     )
 )
 
+# breath options
 breathe_default_project = "Ceph"
 # see $(top_srcdir)/Doxyfile
 
@@ -118,6 +126,7 @@ breathe_doxygen_config_options = {
     'PREDEFINED': 'CEPH_RADOS_API= '
 }
 
+# edit_on_github options
 # the docs are rendered with github links pointing to master. the javascript
 # snippet in _static/ceph.js rewrites the edit links when a page is loaded, to
 # point to the correct branch.
@@ -144,19 +153,6 @@ def generate_state_diagram(input_paths, output_path):
     return process
 
 
-# handles edit-on-github and old version warning display
-def setup(app):
-    app.add_js_file('js/ceph.js')
-    if ditaa is None:
-        # add "ditaa" as an alias of "diagram"
-        from plantweb.directive import DiagramDirective
-        app.add_directive('ditaa', DiagramDirective)
-    app.connect('builder-inited',
-                generate_state_diagram(['src/osd/PeeringState.h',
-                                        'src/osd/PeeringState.cc'],
-                                       'doc/dev/peering_graph.generated.dot'))
-
-
 # mocking ceph_module offered by ceph-mgr. `ceph_module` is required by
 # mgr.mgr_module
 class Dummy(object):
@@ -180,11 +176,10 @@ class Mock(object):
         return mock
 
 
+# autodoc options
 sys.modules['ceph_module'] = Mock()
 
 if build_with_rtd:
-    exclude_patterns += ['**/api/*',
-                         '**/api.rst']
     autodoc_mock_imports = ['cephfs',
                             'rados',
                             'rbd',
@@ -200,3 +195,16 @@ for c in pybinds:
     pybind = os.path.join(top_level, 'src', c)
     if pybind not in sys.path:
         sys.path.insert(0, pybind)
+
+
+# handles edit-on-github and old version warning display
+def setup(app):
+    app.add_js_file('js/ceph.js')
+    if ditaa is None:
+        # add "ditaa" as an alias of "diagram"
+        from plantweb.directive import DiagramDirective
+        app.add_directive('ditaa', DiagramDirective)
+    app.connect('builder-inited',
+                generate_state_diagram(['src/osd/PeeringState.h',
+                                        'src/osd/PeeringState.cc'],
+                                       'doc/dev/peering_graph.generated.dot'))