1# -*- coding: utf-8 -*-
2#
3# Configuration file for the Sphinx documentation builder.
4#
5# This file does only contain a selection of the most common options. For a
6# full list see the documentation:
7# http://www.sphinx-doc.org/en/master/config
8
9# -- Path setup --------------------------------------------------------------
10
11# If extensions (or modules to document with autodoc) are in another directory,
12# add these directories to sys.path here. If the directory is relative to the
13# documentation root, use os.path.abspath to make it absolute, like shown here.
14#
15import os
16# import sys
17# sys.path.insert(0, os.path.abspath('.'))
18
19# to avoid "sphinx.errors.SphinxParallelError: RecursionError: maximum recursion depth exceeded while pickling an object"
20import sys
21sys.setrecursionlimit(5000)
22
23# -- Project information -----------------------------------------------------
24
25project = 'Kea'
26copyright = '2019-2020, Internet Systems Consortium'
27author = 'Internet Systems Consortium'
28
29# get current kea version
30config_ac_path = '../../configure.ac'
31changelog_path = '../../ChangeLog'
32release = 'UNRELEASED'
33with open(config_ac_path) as f:
34    for line in f.readlines():
35        if line.startswith('AC_INIT(kea'):
36            parts = line.split(',')
37            release = parts[1]
38            # If the first line of the ChangeLog announces release, it means
39            # that this is the final release.
40            dash_parts = release.split('-')
41            candidate_release = dash_parts[0]
42            with open(changelog_path) as changelog_file:
43                first_line = changelog_file.readline()
44                if candidate_release in first_line and "released" in first_line:
45                    release = candidate_release
46            break
47version = release
48
49# -- General configuration ---------------------------------------------------
50
51# If your documentation needs a minimal Sphinx version, state it here.
52#
53# needs_sphinx = '1.0'
54
55# Add any Sphinx extension module names here, as strings. They can be
56# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
57# ones.
58extensions = [
59    'sphinx.ext.todo',
60    'sphinx.ext.mathjax',
61]
62
63# The suffix(es) of source filenames.
64# You can specify multiple suffix as a list of string:
65#
66# source_suffix = ['.rst', '.md']
67source_suffix = '.rst'
68
69# The master toctree document.
70master_doc = 'index'
71
72# Additional docs
73messages_doc = 'kea-messages'
74
75# The language for content autogenerated by Sphinx. Refer to documentation
76# for a list of supported languages.
77#
78# This is also used if you do content translation via gettext catalogs.
79# Usually you set "language" from the command line for these cases.
80language = None
81
82# List of patterns, relative to source directory, that match files and
83# directories to ignore when looking for source files.
84# This pattern also affects html_static_path and html_extra_path.
85exclude_patterns = [
86    '_build', 'Thumbs.db', '.DS_Store',
87    # included files need to be excluded to avoid duplicate labels
88    'arm/platforms.rst',
89    'arm/hooks-bootp.rst',
90    'arm/hooks-class-cmds.rst',
91    'arm/hooks-cb-cmds.rst',
92    'arm/config-backend.rst',
93    'arm/hooks-ha.rst',
94    'arm/hooks-host-cache.rst',
95    'arm/hooks-lease-cmds.rst',
96    'arm/hooks-lease-query.rst',
97    'arm/hooks-radius.rst',
98    'arm/hooks-run-script.rst',
99    'arm/hooks-stat-cmds.rst',
100    'arm/hammer.rst',
101    'arm/ext-netconf.rst',
102    'arm/ext-gss-tsig.rst',
103    'grammar/grammar-ca-parser.rst',
104    'grammar/grammar-d2-parser.rst',
105    'grammar/grammar-dhcp4-parser.rst',
106    'grammar/grammar-dhcp6-parser.rst',
107    'grammar/grammar-netconf-parser.rst',
108]
109
110# The name of the Pygments (syntax highlighting) style to use.
111pygments_style = None
112
113
114# -- Options for HTML output -------------------------------------------------
115
116# The theme to use for HTML and HTML Help pages.  See the documentation for
117# a list of builtin themes.
118#
119#html_theme = 'alabaster'
120html_theme = 'sphinx_rtd_theme'
121html_logo = 'static/kea-imageonly-100bw.png'
122
123# Theme options are theme-specific and customize the look and feel of a theme
124# further.  For a list of options available for each theme, see the
125# documentation.
126#
127#html_theme_options = {
128#    "logo": "kea-logo-100x70.png",
129#}
130
131# Add any paths that contain custom static files (such as style sheets) here,
132# relative to this directory. They are copied after the builtin static files,
133# so a file named "default.css" will overwrite the builtin "default.css".
134html_static_path = ['static']
135
136# Custom sidebar templates, must be a dictionary that maps document names
137# to template names.
138#
139# The default sidebars (for documents that don't match any pattern) are
140# defined by theme itself.  Builtin themes are using these templates by
141# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
142# 'searchbox.html']``.
143#
144# html_sidebars = {}
145
146
147# -- Options for HTMLHelp output ---------------------------------------------
148
149# Output file base name for HTML help builder.
150#htmlhelp_basename = 'KeaAdministratorReferenceManualdoc'
151
152
153# -- Options for LaTeX output ------------------------------------------------
154
155latex_elements = {
156    # The paper size ('letterpaper' or 'a4paper').
157    #
158    # 'papersize': 'letterpaper',
159
160    # The font size ('10pt', '11pt' or '12pt').
161    #
162    # 'pointsize': '10pt',
163
164    # Additional stuff for the LaTeX preamble.
165    #
166    # 'preamble': '',
167
168    # Latex figure (float) alignment
169    #
170    # 'figure_align': 'htbp',
171}
172
173# Grouping the document tree into LaTeX files. List of tuples
174# (source start file, target name, title,
175#  author, documentclass [howto, manual, or own class]).
176latex_documents = [
177    (master_doc, 'kea-arm.tex', 'Kea Administrator Reference Manual Documentation', author, 'manual'),
178]
179
180latex_logo = 'static/kea-logo-200.png'
181
182if os.getenv("READTHEDOCS", "False") == "False":
183    latex_documents.append((messages_doc, 'kea-messages.tex', 'Kea Messages Manual', author, 'manual'))
184
185
186# -- Options for manual page output ------------------------------------------
187
188# One entry per manual page. List of tuples
189# (source start file, name, description, authors, manual section).
190man_pages = [
191    (master_doc, 'kea-arm', 'Kea Administrator Reference Manual Documentation', [author], 1),
192    ('man/kea-admin.8', 'kea-admin', 'Shell script for managing Kea databases', author, 8),
193    ('man/keactrl.8', 'keactrl', 'Shell script for managing Kea', author, 8),
194    ('man/kea-ctrl-agent.8', 'kea-ctrl-agent', 'Control Agent process in Kea', author, 8),
195    ('man/kea-dhcp4.8', 'kea-dhcp4', 'DHCPv4 server in Kea', author, 8),
196    ('man/kea-dhcp6.8', 'kea-dhcp6', 'DHCPv6 server in Kea', author, 8),
197    ('man/kea-dhcp-ddns.8', 'kea-dhcp-ddns', 'DHCP-DDNS process in Kea', author, 8),
198    ('man/kea-lfc.8', 'kea-lfc', 'Lease File Cleanup process in Kea', author, 8),
199    ('man/kea-netconf.8', 'kea-netconf', 'NETCONF agent for configuring Kea', author, 8),
200    ('man/kea-shell.8', 'kea-shell', 'Text client for Control Agent process', author, 8),
201    ('man/perfdhcp.8', 'perfdhcp', 'DHCP benchmarking tool', author, 8),
202]
203
204
205# -- Extension configuration -------------------------------------------------
206
207# -- Options for todo extension ----------------------------------------------
208
209# If true, `todo` and `todoList` produce output, else they produce nothing.
210todo_include_todos = True
211
212
213
214# Do generation of api.rst and kea-messages.rst here in conf.py instead of Makefile.am
215# so they are available on ReadTheDocs as there makefiles are not used for building docs.
216def run_generate_docs(_):
217    import os
218    import sys
219    src_dir = os.path.abspath(os.path.dirname(__file__))
220    print(src_dir)
221    sys.path.append(src_dir)
222
223    import api2doc
224    with open(os.path.join(src_dir, 'api-files.txt')) as af:
225        api_files = af.read().split()
226    api_files = [os.path.abspath(os.path.join(src_dir, '../..', af)) for af in api_files]
227    api2doc.generate(api_files, os.path.join(src_dir, 'api.rst'))
228
229    import mes2doc
230    with open(os.path.join(src_dir, 'mes-files.txt')) as mf:
231        mes_files = mf.read().split()
232    mes_files = [os.path.abspath(os.path.join(src_dir, '../..', mf)) for mf in mes_files]
233    mes2doc.generate(mes_files, os.path.join(src_dir, 'kea-messages.rst'))
234
235    # Sphinx has some limitations. It can't import files from outside its directory, which
236    # in our case is src/sphinx. On the other hand, we need to have platforms.rst file
237    # in top level directory, so it's easily accessible by prospective and first time
238    # users. Furthermore, ReadTheDocs does not use the makefile system at all and they rely
239    # on sphinx-build only. As a result we need to conduct some Makefile-like operations
240    # here. This requires us to copy (or link) the file from the top level to sphinx subdir.
241    #
242    # The first entry on this list is the actual file to copy, the second is a unique name
243    # that will be used when copied over to arm/ directory.
244    FILES_TO_COPY = [
245        [ '../../platforms.rst', 'platforms.rst' ],
246        [ '../examples/template-power-user-home/info.md', 'template-power-user-home.md' ],
247        [ '../examples/template-power-user-home/kea-ca-1.conf', 'template-power-user-home-ca-1.conf' ],
248        [ '../examples/template-power-user-home/kea-ca-2.conf', 'template-power-user-home-ca-2.conf' ],
249        [ '../examples/template-power-user-home/kea-dhcp4-1.conf', 'template-power-user-home-dhcp4-1.conf' ],
250        [ '../examples/template-power-user-home/kea-dhcp4-2.conf', 'template-power-user-home-dhcp4-2.conf' ]
251    ]
252
253    from shutil import copyfile
254    for [a, b] in FILES_TO_COPY:
255        src = os.path.join(src_dir, a)
256        dst = os.path.join(src_dir, 'arm', b)
257        print("Copying %s to %s" % (src, dst))
258        copyfile(src, dst)
259
260# custom setup hook
261def setup(app):
262    if hasattr(app, 'add_css_file'):
263        app.add_css_file('kea.css')
264    else:
265        app.add_stylesheet('kea.css')
266
267    app.connect('builder-inited', run_generate_docs)
268