From a1e276e1d328cf3cc871da409fa098ebc428a62a Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Wed, 31 Jan 2018 15:59:26 -0500 Subject: doc: overhaul manpages * Remove groff manpages * Rewrite manpages in RST * Clean up and standardize manpage content Signed-off-by: Quentin Young --- doc/manpages/conf.py | 347 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 doc/manpages/conf.py (limited to 'doc/manpages/conf.py') diff --git a/doc/manpages/conf.py b/doc/manpages/conf.py new file mode 100644 index 0000000000..6aa8588039 --- /dev/null +++ b/doc/manpages/conf.py @@ -0,0 +1,347 @@ +# -*- coding: utf-8 -*- +# +# FRR documentation build configuration file, created by +# sphinx-quickstart on Tue Jan 31 16:00:52 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import re + +# 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 +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '1.0' + +# prolog for various variable substitutions +rst_prolog = '' + +# 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'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'FRR' +copyright = u'2017, FRR' +author = u'Kunihiro Ishiguro, et al.' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +# The short X.Y version. +version = u'?.?' +# The full version, including alpha/beta/rc tags. +release = u'?.?-?' + + +# ----------------------------------------------------------------------------- +# Extract values from codebase for substitution into docs. +# ----------------------------------------------------------------------------- + +# Various installation prefixes. Reasonable defaults are set where possible. +# Values are overridden by logic below. +replace_vars = { + 'AUTHORS': author, + 'COPYRIGHT_YEAR': '1999-2005', + 'COPYRIGHT_STR': None, + 'PACKAGE_NAME': project.lower(), + 'PACKAGE_TARNAME': project.lower(), + 'PACKAGE_STRING': None, + '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, + '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) + +# manually fill out some of these we can't get from config.status +replace_vars['COPYRIGHT_STR'] = "Copyright (c)" +replace_vars['COPYRIGHT_STR'] += ' {}'.format(replace_vars['COPYRIGHT_YEAR']) +replace_vars['COPYRIGHT_STR'] += ' {}'.format(replace_vars['AUTHORS']) +release = replace_vars['PACKAGE_VERSION'] +version = release.split('-')[0] + +# add substitutions to prolog +for key, value in replace_vars.items(): + rst_prolog += '.. |{0}| replace:: {1}\n'.format(key, value) + + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinx_rtd_theme' + +# 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 = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'FRRdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'FRR.tex', u'FRR User Manual', + u'FRR', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). + +# If true, show URL addresses after external links. +#man_show_urls = False + +fwfrr = "{} routing engine for use with FRRouting." + +man_pages = [ + ('bgpd', 'bgpd', fwfrr.format("a BGPv4, BGPv4+, BGPv4- "), [], 8), + ('eigrpd', 'eigrpd', fwfrr.format("an EIGRP "), [], 8), + ('ospf6d', 'ospf6d', fwfrr.format("an OSPFv3 "), [], 8), + ('ospfd', 'ospfd', fwfrr.format("an OSPFv2 "), [], 8), + ('isisd', 'isisd', fwfrr.format("an IS-IS "), [], 8), + ('ospfclient', 'ospfclient', 'an example ospf-api client', [], 8), + ('ldpd', 'ldpd', fwfrr.format("an LDP "), [], 8), + ('nhrpd', 'nhrpd', fwfrr.format("a Next Hop Routing Protocol "), [], 8), + ('pimd', 'pimd', fwfrr.format("a PIM "), [], 8), + ('ripd', 'ripd', fwfrr.format("a RIP "), [], 8), + ('ripngd', 'ripngd', fwfrr.format("a RIPNG "), [], 8), + ('zebra', 'zebra', 'a routing manager for use with associated FRRouting components.', [], 8), + ('watchfrr', 'watchfrr', 'a program to monitor the status of FRRouting daemons', [], 8), + ('vtysh', 'vtysh', 'an integrated shell for FRRouting.', [], 1), + ('frr', 'frr', 'a systemd interaction script', [], 1), +] + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + +# custom extensions here -- cgit v1.2.3 From 12b7724ff82caf19beb9c20e570a43af8d343674 Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Wed, 7 Feb 2018 13:36:03 -0500 Subject: doc: fix toctree warning in manpages Forgot to add a couple includes to the exclude list. Also move defines.txt to defines.rst since I know how to properly ignore things now. Signed-off-by: Quentin Young --- doc/manpages/bgpd.rst | 2 +- doc/manpages/conf.py | 2 +- doc/manpages/defines.rst | 3 +++ doc/manpages/defines.txt | 3 --- doc/manpages/eigrpd.rst | 2 +- doc/manpages/isisd.rst | 2 +- doc/manpages/ldpd.rst | 2 +- doc/manpages/nhrpd.rst | 2 +- doc/manpages/ospf6d.rst | 2 +- doc/manpages/ospfd.rst | 2 +- doc/manpages/pimd.rst | 2 +- doc/manpages/ripd.rst | 2 +- doc/manpages/ripngd.rst | 2 +- doc/manpages/vtysh.rst | 2 +- doc/manpages/watchfrr.rst | 2 +- doc/manpages/zebra.rst | 2 +- 16 files changed, 17 insertions(+), 17 deletions(-) create mode 100644 doc/manpages/defines.rst delete mode 100644 doc/manpages/defines.txt (limited to 'doc/manpages/conf.py') diff --git a/doc/manpages/bgpd.rst b/doc/manpages/bgpd.rst index 73ca6b2351..94213db4d7 100644 --- a/doc/manpages/bgpd.rst +++ b/doc/manpages/bgpd.rst @@ -2,7 +2,7 @@ BGPD **** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: bgpd SYNOPSIS diff --git a/doc/manpages/conf.py b/doc/manpages/conf.py index 6aa8588039..403e86e55e 100644 --- a/doc/manpages/conf.py +++ b/doc/manpages/conf.py @@ -125,7 +125,7 @@ language = None # 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', 'common-options.rst', 'epilogue.rst', 'defines.rst'] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/doc/manpages/defines.rst b/doc/manpages/defines.rst new file mode 100644 index 0000000000..4b66d71b44 --- /dev/null +++ b/doc/manpages/defines.rst @@ -0,0 +1,3 @@ +.. |synopsis-options| replace:: [-d|-t|-dt] [-C] [-f config-file] [-i pid-file] [-z zclient-path] [-u user] [-g group] [-A vty-addr] [-P vty-port] [-M module[:options]] [-N pathspace] [--vty_socket vty-path] [--moduledir module-path] +.. |synopsis-options-hv| replace:: [-h] [-v] +.. |seealso-programs| replace:: zebra(8), vtysh(1), ripd(8), ripngd(8), ospfd(8), ospf6d(8), bgpd(8), isisd(8), babeld(8), nhrpd(8), pimd(8), ldpd(8), eigrpd(8) diff --git a/doc/manpages/defines.txt b/doc/manpages/defines.txt deleted file mode 100644 index 4b66d71b44..0000000000 --- a/doc/manpages/defines.txt +++ /dev/null @@ -1,3 +0,0 @@ -.. |synopsis-options| replace:: [-d|-t|-dt] [-C] [-f config-file] [-i pid-file] [-z zclient-path] [-u user] [-g group] [-A vty-addr] [-P vty-port] [-M module[:options]] [-N pathspace] [--vty_socket vty-path] [--moduledir module-path] -.. |synopsis-options-hv| replace:: [-h] [-v] -.. |seealso-programs| replace:: zebra(8), vtysh(1), ripd(8), ripngd(8), ospfd(8), ospf6d(8), bgpd(8), isisd(8), babeld(8), nhrpd(8), pimd(8), ldpd(8), eigrpd(8) diff --git a/doc/manpages/eigrpd.rst b/doc/manpages/eigrpd.rst index ef269b1151..bc824468d0 100644 --- a/doc/manpages/eigrpd.rst +++ b/doc/manpages/eigrpd.rst @@ -2,7 +2,7 @@ EIGRPD ****** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: eigrpd SYNOPSIS diff --git a/doc/manpages/isisd.rst b/doc/manpages/isisd.rst index 6926d56051..68761f642c 100644 --- a/doc/manpages/isisd.rst +++ b/doc/manpages/isisd.rst @@ -2,7 +2,7 @@ ISISD ***** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: isisd SYNOPSIS diff --git a/doc/manpages/ldpd.rst b/doc/manpages/ldpd.rst index e01027d1f7..113f06673e 100644 --- a/doc/manpages/ldpd.rst +++ b/doc/manpages/ldpd.rst @@ -2,7 +2,7 @@ LDPD **** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: ldpd SYNOPSIS diff --git a/doc/manpages/nhrpd.rst b/doc/manpages/nhrpd.rst index 8a2cb25611..cae01c677b 100644 --- a/doc/manpages/nhrpd.rst +++ b/doc/manpages/nhrpd.rst @@ -2,7 +2,7 @@ NHRPD ***** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: nhrpd SYNOPSIS diff --git a/doc/manpages/ospf6d.rst b/doc/manpages/ospf6d.rst index 2328d240ae..cfc6860d5c 100644 --- a/doc/manpages/ospf6d.rst +++ b/doc/manpages/ospf6d.rst @@ -2,7 +2,7 @@ OSPF6D ****** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: ospf6d SYNOPSIS diff --git a/doc/manpages/ospfd.rst b/doc/manpages/ospfd.rst index 50ee503730..6e4d093f69 100644 --- a/doc/manpages/ospfd.rst +++ b/doc/manpages/ospfd.rst @@ -2,7 +2,7 @@ OSPFD ***** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: ospfd SYNOPSIS diff --git a/doc/manpages/pimd.rst b/doc/manpages/pimd.rst index 98fd3a5c92..d7582668d2 100644 --- a/doc/manpages/pimd.rst +++ b/doc/manpages/pimd.rst @@ -2,7 +2,7 @@ PIMD **** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: pimd SYNOPSIS diff --git a/doc/manpages/ripd.rst b/doc/manpages/ripd.rst index 01b0223251..af4590c824 100644 --- a/doc/manpages/ripd.rst +++ b/doc/manpages/ripd.rst @@ -2,7 +2,7 @@ RIPD **** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: ripd SYNOPSIS diff --git a/doc/manpages/ripngd.rst b/doc/manpages/ripngd.rst index 2a3e14ae6f..aedd689876 100644 --- a/doc/manpages/ripngd.rst +++ b/doc/manpages/ripngd.rst @@ -2,7 +2,7 @@ RIPNGD ****** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: ripngd SYNOPSIS diff --git a/doc/manpages/vtysh.rst b/doc/manpages/vtysh.rst index 341d5eae44..38cb668e82 100644 --- a/doc/manpages/vtysh.rst +++ b/doc/manpages/vtysh.rst @@ -2,7 +2,7 @@ VTYSH ***** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: eigrpd SYNOPSIS diff --git a/doc/manpages/watchfrr.rst b/doc/manpages/watchfrr.rst index 5c18ac2e6a..f0b733298d 100644 --- a/doc/manpages/watchfrr.rst +++ b/doc/manpages/watchfrr.rst @@ -2,7 +2,7 @@ WATCHFRR ******** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: watchfrr SYNOPSIS diff --git a/doc/manpages/zebra.rst b/doc/manpages/zebra.rst index 9e5d4deb07..268b1d8645 100644 --- a/doc/manpages/zebra.rst +++ b/doc/manpages/zebra.rst @@ -2,7 +2,7 @@ ZEBRA ***** -.. include:: defines.txt +.. include:: defines.rst .. |DAEMON| replace:: zebra SYNOPSIS -- cgit v1.2.3 From 6c749456224b383a95e717c95cdb6289eb9cb5e4 Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Wed, 7 Feb 2018 19:22:52 -0500 Subject: doc: use python 2.6 format strings Centos 6 only has python 2.6 which requires numerical identifiers for format strings Signed-off-by: Quentin Young --- doc/developer/conf.py | 4 ++-- doc/manpages/conf.py | 6 +++--- doc/user/conf.py | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) (limited to 'doc/manpages/conf.py') diff --git a/doc/developer/conf.py b/doc/developer/conf.py index e4c56f54c3..1cb1d45af6 100644 --- a/doc/developer/conf.py +++ b/doc/developer/conf.py @@ -98,8 +98,8 @@ with open('../../config.status', 'r') as cfgstatus: # manually fill out some of these we can't get from config.status replace_vars['COPYRIGHT_STR'] = "Copyright (c)" -replace_vars['COPYRIGHT_STR'] += ' {}'.format(replace_vars['COPYRIGHT_YEAR']) -replace_vars['COPYRIGHT_STR'] += ' {}'.format(replace_vars['AUTHORS']) +replace_vars['COPYRIGHT_STR'] += ' {0}'.format(replace_vars['COPYRIGHT_YEAR']) +replace_vars['COPYRIGHT_STR'] += ' {0}'.format(replace_vars['AUTHORS']) release = replace_vars['PACKAGE_VERSION'] version = release.split('-')[0] diff --git a/doc/manpages/conf.py b/doc/manpages/conf.py index 403e86e55e..6da6ebff0a 100644 --- a/doc/manpages/conf.py +++ b/doc/manpages/conf.py @@ -100,8 +100,8 @@ with open('../../config.status', 'r') as cfgstatus: # manually fill out some of these we can't get from config.status replace_vars['COPYRIGHT_STR'] = "Copyright (c)" -replace_vars['COPYRIGHT_STR'] += ' {}'.format(replace_vars['COPYRIGHT_YEAR']) -replace_vars['COPYRIGHT_STR'] += ' {}'.format(replace_vars['AUTHORS']) +replace_vars['COPYRIGHT_STR'] += ' {0}'.format(replace_vars['COPYRIGHT_YEAR']) +replace_vars['COPYRIGHT_STR'] += ' {0}'.format(replace_vars['AUTHORS']) release = replace_vars['PACKAGE_VERSION'] version = release.split('-')[0] @@ -306,7 +306,7 @@ latex_documents = [ # If true, show URL addresses after external links. #man_show_urls = False -fwfrr = "{} routing engine for use with FRRouting." +fwfrr = "{0} routing engine for use with FRRouting." man_pages = [ ('bgpd', 'bgpd', fwfrr.format("a BGPv4, BGPv4+, BGPv4- "), [], 8), diff --git a/doc/user/conf.py b/doc/user/conf.py index 6aa97de304..bd1bf6c041 100644 --- a/doc/user/conf.py +++ b/doc/user/conf.py @@ -98,8 +98,8 @@ with open('../../config.status', 'r') as cfgstatus: # manually fill out some of these we can't get from config.status replace_vars['COPYRIGHT_STR'] = "Copyright (c)" -replace_vars['COPYRIGHT_STR'] += ' {}'.format(replace_vars['COPYRIGHT_YEAR']) -replace_vars['COPYRIGHT_STR'] += ' {}'.format(replace_vars['AUTHORS']) +replace_vars['COPYRIGHT_STR'] += ' {0}'.format(replace_vars['COPYRIGHT_YEAR']) +replace_vars['COPYRIGHT_STR'] += ' {0}'.format(replace_vars['AUTHORS']) release = replace_vars['PACKAGE_VERSION'] version = release.split('-')[0] -- cgit v1.2.3 From edc33b2f22e790cfe3e60de869baf17d0c8c65e0 Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Wed, 7 Mar 2018 14:35:20 -0500 Subject: doc: fix make setup Iron out all of the glitches with recursive Automake, 3rd-party autogenerated Sphinx makefiles, building and installing 3 different document formats under different targets, and handling clean. * Implement all Automake-required targets for 3rd-party Makefiles * Setup subdirectories for 3rd-party Makefiles * Override implicit Automake document targets * Clean up explicit targets for developer docs * Move Sphinx-generated Makefile to an include file * Update targets for debian packaging Signed-off-by: Quentin Young --- debianpkg/backports/ubuntu12.04/debian/rules | 4 +- debianpkg/backports/ubuntu14.04/debian/rules | 4 +- debianpkg/rules | 4 +- doc/Makefile.am | 74 +++++--- doc/developer/Makefile | 220 +-------------------- doc/frr-sphinx.mk | 219 +++++++++++++++++++++ doc/manpages/Makefile | 267 +++++--------------------- doc/manpages/conf.py | 2 +- doc/user/Makefile | 274 ++++++--------------------- 9 files changed, 376 insertions(+), 692 deletions(-) create mode 100644 doc/frr-sphinx.mk (limited to 'doc/manpages/conf.py') diff --git a/debianpkg/backports/ubuntu12.04/debian/rules b/debianpkg/backports/ubuntu12.04/debian/rules index 83e5e9689e..9a3ea1ffbd 100755 --- a/debianpkg/backports/ubuntu12.04/debian/rules +++ b/debianpkg/backports/ubuntu12.04/debian/rules @@ -139,10 +139,10 @@ override_dh_auto_configure: override_dh_auto_build: ifeq ($(GENERATE_PDF), 1) - dh_auto_build -- -C doc user.pdf + dh_auto_build -- -C doc pdf endif rm -vf doc/user/_build/texinfo/frr.info - dh_auto_build -- -C doc frr.info + dh_auto_build -- -C doc info override_dh_auto_test: diff --git a/debianpkg/backports/ubuntu14.04/debian/rules b/debianpkg/backports/ubuntu14.04/debian/rules index 64a3d7b63e..20b821ead7 100755 --- a/debianpkg/backports/ubuntu14.04/debian/rules +++ b/debianpkg/backports/ubuntu14.04/debian/rules @@ -143,10 +143,10 @@ override_dh_auto_build: # doc/ is a bit crazy ifeq ($(GENERATE_PDF), 1) - dh_auto_build -- -C doc user.pdf + dh_auto_build -- -C doc pdf endif rm -vf doc/_build/texinfo/frr.info - dh_auto_build -- -C doc frr.info + dh_auto_build -- -C doc info override_dh_auto_test: diff --git a/debianpkg/rules b/debianpkg/rules index 46f8f48028..82a5148039 100755 --- a/debianpkg/rules +++ b/debianpkg/rules @@ -141,10 +141,10 @@ override_dh_auto_configure: override_dh_auto_build: # doc/ is a bit crazy ifeq ($(GENERATE_PDF), 1) - dh_auto_build -- -C doc user.pdf + dh_auto_build -- -C doc pdf endif rm -vf doc/user/_build/texinfo/frr.info - dh_auto_build -- -C doc frr.info + dh_auto_build -- -C doc info override_dh_auto_test: diff --git a/doc/Makefile.am b/doc/Makefile.am index 4a9b0525a5..62f3ae2b6a 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,11 +1,20 @@ ## Process this file with automake to produce Makefile.in. -# Tell Automake to invoke 'make' in the manpages directory with argument 'man' -SUBDIRS = manpages +# Pass down make invocation to each subdirectory. +# +# Each of these directories contains a Sphinx-generated Makefile that has been +# modified to implement all the targets required by Automake, as documented in +# the 'Third-Party Makefiles' section of the Automake docs. +# +# Note the absence of the 'developer' directory here; development docs are +# never built as part of a regular build. They are only built when explicitly +# asked for. See comment further down. +SUBDIRS = manpages user +AM_MAKEFLAGS = DESTDIR=${DESTDIR} infodir=${infodir} MANPAGE_BUILDDIR = manpages/_build/man -# Once that is done these will all exist +# This is a hack, see comment further down. man_MANS = $(MANPAGE_BUILDDIR)/frr.1 if PIMD @@ -65,32 +74,49 @@ if EIGRPD man_MANS += $(MANPAGE_BUILDDIR)/eigrpd.8 endif -# handled by subdir target -man: ; - -# explicit targets -frr.info: - $(MAKE) -C user info - -user.pdf: - $(MAKE) -C user latexpdf - -user.html: - $(MAKE) -C user html - -developer.pdf: +# Automake is particular about manpages. It is aware of them and has some +# special facilities for handling them, but it assumes that manpages are always +# given in groff source and so these facilities are limited to simply +# specifying the path to the groff sources in a special variable. There is no +# target for building manpages that can be extended, as there are for pdf, +# html, dvi, etc. Unfortunately this leaves us with hijacking the +# 'install-data' and 'all' targets in the 3rd-party Makefile in manpages/ to +# make sure manpages are always built, and then using the special Automake +# variable defined above in order to take advantage of automatic installation. +# +# However, it is conceivable that someone may want to build just the manpages, +# so here's an explicit target for that. +man: + $(MAKE) -C manpages man + +# Automake automatically defines targets for various document formats. All of +# the child 3rd-party Makefiles are aware of all Automake targets and implement +# the ones we are interested in. +# +# The SUBDIRS variable at the top of this Makefile.am causes the following +# implicit Automake targets to only build user documentation, and not developer +# documentation: +# - info +# - html +# - pdf +# +# If you wish to build developer documentation, use these targets: +developer-info: + $(MAKE) -C developer info + +developer-pdf: $(MAKE) -C developer latexpdf -developer.html: +developer-html: $(MAKE) -C developer html -# info target, handled by automake installation -install-data-local: frr.info - install -d ${DESTDIR}${infodir} - gzip < user/_build/texinfo/frr.info > ${DESTDIR}${infodir}/frr.info.gz - install-info user/_build/texinfo/frr.info ${DESTDIR}${infodir}/dir +# If you want to build the developer's docs in other formats, try the +# following: +# +# $ cd developer +# $ make help -# include sources for shipped docs +# dist tarballs want doc sources EXTRA_DIST = manpages/defines.rst \ manpages/ldpd.rst \ manpages/index.rst \ diff --git a/doc/developer/Makefile b/doc/developer/Makefile index f5aca7a655..9807a750bf 100644 --- a/doc/developer/Makefile +++ b/doc/developer/Makefile @@ -1,219 +1 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -PAPER ?= -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -SPHINXBUILD = sphinx-1.0-build -endif -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/") -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -.PHONY: clean -clean: - rm -rf $(BUILDDIR)/* - -.PHONY: html -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: dirhtml -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -.PHONY: singlehtml -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -.PHONY: pickle -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -.PHONY: json -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -.PHONY: htmlhelp -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -.PHONY: qthelp -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/FRR.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FRR.qhc" - -.PHONY: applehelp -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -.PHONY: devhelp -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/FRR" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FRR" - @echo "# devhelp" - -.PHONY: epub -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -.PHONY: latex -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -.PHONY: latexpdf -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: latexpdfja -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: text -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -.PHONY: man -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -.PHONY: texinfo -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -.PHONY: info -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - $(MAKE) -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -.PHONY: gettext -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -.PHONY: changes -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -.PHONY: linkcheck -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -.PHONY: doctest -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -.PHONY: coverage -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -.PHONY: xml -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -.PHONY: pseudoxml -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." +include ../frr-sphinx.mk diff --git a/doc/frr-sphinx.mk b/doc/frr-sphinx.mk new file mode 100644 index 0000000000..f5aca7a655 --- /dev/null +++ b/doc/frr-sphinx.mk @@ -0,0 +1,219 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +PAPER ?= +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +SPHINXBUILD = sphinx-1.0-build +endif +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/") +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/FRR.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FRR.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/FRR" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FRR" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + $(MAKE) -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/manpages/Makefile b/doc/manpages/Makefile index 33a3af1f14..ebbbc31009 100644 --- a/doc/manpages/Makefile +++ b/doc/manpages/Makefile @@ -1,227 +1,48 @@ -# Makefile for Sphinx documentation -# +include ../frr-sphinx.mk + +# ----------------------------------------------------------------------------- +# Automake requires that 3rd-party Makefiles recognize these targets. +# ----------------------------------------------------------------------------- +# install +# install-data +# install-exec +# uninstall +# install-dvi +# install-html +# install-info +# install-ps +# install-pdf +# installdirs +# check +# installcheck +# mostlyclean +# clean +# distclean +# maintainer-clean +# dvi +# pdf +# ps +# info +# html +# tags +# ctags + +# ignore these targets +EMPTY_AUTOMAKE_TARGETS = dvi pdf ps tags ctags distdir installdirs check installcheck install-dvi install-ps install-html install-pdf install-info install-exec +.PHONY: $(EMPTY_AUTOMAKE_TARGETS) +$(EMPTY_AUTOMAKE_TARGETS): + +# These targets are automatically generated by Sphinx but conflict with +# implicitly defined Automake rules, so we manually override them to nothing. +# The other option is deleting the Sphinx-generated rules, which suppresses the +# warning but kinda screws up the symmetry between Makefiles. +info: ; +html: ; + +all: man -# You can set these variables from the command line. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -PAPER ?= -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -SPHINXBUILD = sphinx-1.0-build -endif -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/") -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -.PHONY: clean -clean: - rm -rf $(BUILDDIR)/* - -.PHONY: html -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: dirhtml -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -.PHONY: singlehtml -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -.PHONY: pickle -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -.PHONY: json -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -.PHONY: htmlhelp -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -.PHONY: qthelp -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/FRR.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FRR.qhc" - -.PHONY: applehelp -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -.PHONY: devhelp -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/FRR" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FRR" - @echo "# devhelp" - -.PHONY: epub -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -.PHONY: latex -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -.PHONY: latexpdf -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: latexpdfja -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: text -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -.PHONY: man -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -.PHONY: texinfo -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -.PHONY: info -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -.PHONY: gettext -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -.PHONY: changes -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -.PHONY: linkcheck -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -.PHONY: doctest -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -.PHONY: coverage -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -.PHONY: xml -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -.PHONY: pseudoxml -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -.PHONY: install-data install-data: man -.PHONY: all -all: install-data +install: install-data -%: ; +mostlyclean distclean maintainer-clean: clean diff --git a/doc/manpages/conf.py b/doc/manpages/conf.py index 2d6fbe8503..50331b6f0a 100644 --- a/doc/manpages/conf.py +++ b/doc/manpages/conf.py @@ -159,7 +159,7 @@ todo_include_todos = True # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' +html_theme = 'classic' # 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 diff --git a/doc/user/Makefile b/doc/user/Makefile index f5aca7a655..ad2abb25c1 100644 --- a/doc/user/Makefile +++ b/doc/user/Makefile @@ -1,219 +1,55 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -PAPER ?= -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -SPHINXBUILD = sphinx-1.0-build -endif -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/") -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -.PHONY: clean -clean: - rm -rf $(BUILDDIR)/* - -.PHONY: html -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: dirhtml -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -.PHONY: singlehtml -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -.PHONY: pickle -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -.PHONY: json -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -.PHONY: htmlhelp -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -.PHONY: qthelp -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/FRR.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FRR.qhc" - -.PHONY: applehelp -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -.PHONY: devhelp -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/FRR" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FRR" - @echo "# devhelp" - -.PHONY: epub -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -.PHONY: latex -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -.PHONY: latexpdf -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: latexpdfja -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: text -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -.PHONY: man -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -.PHONY: texinfo -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -.PHONY: info -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - $(MAKE) -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -.PHONY: gettext -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -.PHONY: changes -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -.PHONY: linkcheck -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -.PHONY: doctest -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -.PHONY: coverage -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -.PHONY: xml -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -.PHONY: pseudoxml -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." +include ../frr-sphinx.mk + +# ----------------------------------------------------------------------------- +# Automake requires that 3rd-party Makefiles recognize these targets. +# ----------------------------------------------------------------------------- +# install +# install-data +# install-exec +# uninstall +# install-dvi +# install-html +# install-info +# install-ps +# install-pdf +# installdirs +# check +# installcheck +# mostlyclean +# clean +# distclean +# maintainer-clean +# dvi +# pdf +# ps +# info +# html +# tags +# ctags + +# ignore these targets +EMPTY_AUTOMAKE_TARGETS = dvi ps tags ctags distdir install-exec install-dvi install-ps installdirs check installcheck install-html install-pdf install-data install +.PHONY: $(EMPTY_AUTOMAKE_TARGETS) +$(EMPTY_AUTOMAKE_TARGETS): + +# When building 'all', the logic is that we want to make docs that are easily +# readable by the person that just built them. Technically the reST source is +# readable in its own right, but we'll also build info and html because those +# offer sequentially better reading experiences. PDF is not built by default +# because it takes quite a while. +all: info html + +# info and html already have built-in sphinx rules; pdf goes to latexpdf +pdf: latexpdf + +# install user manual as info file +install-info: info + install -d ${DESTDIR}${infodir} + gzip < _build/texinfo/frr.info > ${DESTDIR}${infodir}/frr.info.gz + install-info _build/texinfo/frr.info ${DESTDIR}${infodir}/dir + +install-data: install-info + +install: install-data + +mostlyclean distclean maintainer-clean: clean -- cgit v1.2.3 From 37ba370b9eb45c2905c9c411f29c8ecf5e0e4c53 Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Wed, 7 Mar 2018 16:28:23 -0500 Subject: doc: change html theme to 'default' Looks like older versions of Sphinx switched around naming for the default themes. Signed-off-by: Quentin Young --- doc/Makefile.am | 5 +++-- doc/developer/conf.py | 2 +- doc/manpages/conf.py | 2 +- doc/user/conf.py | 2 +- 4 files changed, 6 insertions(+), 5 deletions(-) (limited to 'doc/manpages/conf.py') diff --git a/doc/Makefile.am b/doc/Makefile.am index 62f3ae2b6a..caa909d50d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -10,7 +10,7 @@ # never built as part of a regular build. They are only built when explicitly # asked for. See comment further down. SUBDIRS = manpages user -AM_MAKEFLAGS = DESTDIR=${DESTDIR} infodir=${infodir} +AM_MAKEFLAGS = DESTDIR=${DESTDIR} infodir=${infodir} doczdir=${abs_srcdir} MANPAGE_BUILDDIR = manpages/_build/man @@ -117,7 +117,8 @@ developer-html: # $ make help # dist tarballs want doc sources -EXTRA_DIST = manpages/defines.rst \ +EXTRA_DIST = frr-sphinx.mk \ + manpages/defines.rst \ manpages/ldpd.rst \ manpages/index.rst \ manpages/bgpd.rst \ diff --git a/doc/developer/conf.py b/doc/developer/conf.py index 3f531c14b0..e2293b2a6b 100644 --- a/doc/developer/conf.py +++ b/doc/developer/conf.py @@ -157,7 +157,7 @@ todo_include_todos = True # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'classic' +html_theme = 'default' # 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 diff --git a/doc/manpages/conf.py b/doc/manpages/conf.py index 50331b6f0a..a78e1a2c38 100644 --- a/doc/manpages/conf.py +++ b/doc/manpages/conf.py @@ -159,7 +159,7 @@ todo_include_todos = True # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'classic' +html_theme = 'default' # 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 diff --git a/doc/user/conf.py b/doc/user/conf.py index 817a6d83bb..efe1023740 100644 --- a/doc/user/conf.py +++ b/doc/user/conf.py @@ -157,7 +157,7 @@ todo_include_todos = True # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'classic' +html_theme = 'default' # 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 -- cgit v1.2.3