import sys
import os
import re
+import pygments
+from sphinx.highlighting import lexers
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['sphinx.ext.todo']
+extensions = ['sphinx.ext.todo', 'sphinx.ext.graphviz']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# General information about the project.
project = u'FRR'
copyright = u'2017, FRR'
-author = u'FRR'
+author = u'FRR authors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# Extract values from codebase for substitution into docs.
# -----------------------------------------------------------------------------
-# Various installation prefixes. Reasonable defaults are set where possible.
-# Values are overridden by logic below.
+# Various installation prefixes. Values are extracted from config.status.
+# Reasonable defaults are set in case that file does not exist.
replace_vars = {
- 'AUTHORS': 'Kunihiro Ishiguro, et al.',
+ 'AUTHORS': author,
'COPYRIGHT_YEAR': '1999-2005',
- 'COPYRIGHT_STR': None,
+ 'COPYRIGHT_STR': 'Copyright (c) 1999-2005',
'PACKAGE_NAME': project.lower(),
'PACKAGE_TARNAME': project.lower(),
- 'PACKAGE_STRING': None,
+ 'PACKAGE_STRING': project.lower() + ' latest',
'PACKAGE_URL': 'https://frrouting.org/',
- 'PACKAGE_VERSION': None,
- 'INSTALL_PREFIX_ETC': None,
- 'INSTALL_PREFIX_SBIN': None,
- 'INSTALL_PREFIX_STATE': None,
- 'INSTALL_PREFIX_MODULES': None,
- 'INSTALL_USER': None,
- 'INSTALL_GROUP': None,
- 'INSTALL_VTY_GROUP': None,
+ 'PACKAGE_VERSION': 'latest',
+ 'INSTALL_PREFIX_ETC': '/etc/frr',
+ 'INSTALL_PREFIX_SBIN': '/usr/lib/frr',
+ 'INSTALL_PREFIX_STATE': '/var/run/frr',
+ 'INSTALL_PREFIX_MODULES': '/usr/lib/frr/modules',
+ 'INSTALL_USER': 'frr',
+ 'INSTALL_GROUP': 'frr',
+ 'INSTALL_VTY_GROUP': 'frrvty',
+ 'GROUP': 'frr',
+ 'USER': 'frr',
}
# extract version information, installation location, other stuff we need to
# use when building final documents
val = re.compile('^S\["([^"]+)"\]="(.*)"$')
-with open('../../config.status', 'r') as cfgstatus:
- for ln in cfgstatus.readlines():
- m = val.match(ln)
- if not m or m.group(1) not in replace_vars.keys(): continue
- replace_vars[m.group(1)] = m.group(2)
+try:
+ with open('../../config.status', 'r') as cfgstatus:
+ for ln in cfgstatus.readlines():
+ m = val.match(ln)
+ if not m or m.group(1) not in replace_vars.keys(): continue
+ replace_vars[m.group(1)] = m.group(2)
+except IOError:
+ # if config.status doesn't exist, just ignore it
+ pass
# manually fill out some of these we can't get from config.status
replace_vars['COPYRIGHT_STR'] = "Copyright (c)"
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', 'building-libyang.rst', 'topotests-snippets.rst', 'include-compile.rst']
# The reST default role (used for this markup: `text`) to use for all
# documents.
# a list of builtin themes.
html_theme = 'default'
+try:
+ import sphinx_rtd_theme
+
+ html_theme = 'sphinx_rtd_theme'
+except ImportError:
+ pass
+
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-html_theme_options = {
- 'sidebarbgcolor': '#374249'
-}
+#html_theme_options = {
+# 'sidebarbgcolor': '#374249'
+#}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
+# contents of ../extra/frrlexer.py.
+# This is read here to support VPATH build. Since this section is execfile()'d
+# with the file location, we can safely use a relative path here to save the
+# contents of the lexer file for later use even if our relative path changes
+# due to VPATH.
+with open('../extra/frrlexer.py', 'rb') as lex:
+ frrlexerpy = lex.read()
+
# custom extensions here
def setup(app):
# object type for FRR CLI commands, can be extended to document parent CLI
app.add_object_type('clicmd', 'clicmd')
# css overrides for HTML theme
app.add_stylesheet('overrides.css')
+ # load Pygments lexer for FRR config syntax
+ #
+ # NB: in Pygments 2.2+ this can be done with `load_lexer_from_file`, but we
+ # do it manually since not all of our supported build platforms have 2.2
+ # yet.
+ #
+ # frrlexer = pygments.lexers.load_lexer_from_file('../extra/frrlexer.py', lexername="FRRLexer")
+ custom_namespace = {}
+ exec(frrlexerpy, custom_namespace)
+ lexers['frr'] = custom_namespace['FRRLexer']()