1# Copyright 2020 The Pigweed Authors
2#
3# Licensed under the Apache License, Version 2.0 (the "License"); you may not
4# use this file except in compliance with the License. You may obtain a copy of
5# the License at
6#
7#     https://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12# License for the specific language governing permissions and limitations under
13# the License.
14"""Pigweed's Sphinx configuration."""
15
16import sphinx_rtd_theme
17
18# The suffix of source filenames.
19source_suffix = ['.rst', '.md']
20
21# The master toctree document.
22master_doc = 'index'
23
24# General information about the project.
25project = 'Pigweed'
26copyright = '2020 The Pigweed Authors'  # pylint: disable=redefined-builtin
27
28# The version info for the project you're documenting, acts as replacement for
29# |version| and |release|, also used in various other places throughout the
30# built documents.
31#
32# The short X.Y version.
33version = '0.1'
34# The full version, including alpha/beta/rc tags.
35release = '0.1.0'
36
37# The name of the Pygments (syntax highlighting) style to use.
38pygm = 'sphinx'
39
40extensions = [
41    'sphinx.ext.autodoc',  # Automatic documentation for Python code
42    'sphinx.ext.napoleon',  # Parses Google-style docstrings
43    'm2r',  # Converts Markdown to reStructuredText
44
45    # Blockdiag suite of diagram generators.
46    'sphinxcontrib.blockdiag',
47    'sphinxcontrib.nwdiag',
48    'sphinxcontrib.seqdiag',
49    'sphinxcontrib.actdiag',
50    'sphinxcontrib.rackdiag',
51    'sphinxcontrib.packetdiag',
52]
53
54_DIAG_HTML_IMAGE_FORMAT = 'SVG'
55blockdiag_html_image_format = _DIAG_HTML_IMAGE_FORMAT
56nwdiag_html_image_format = _DIAG_HTML_IMAGE_FORMAT
57seqdiag_html_image_format = _DIAG_HTML_IMAGE_FORMAT
58actdiag_html_image_format = _DIAG_HTML_IMAGE_FORMAT
59rackdiag_html_image_format = _DIAG_HTML_IMAGE_FORMAT
60packetdiag_html_image_format = _DIAG_HTML_IMAGE_FORMAT
61
62# Tell m2r to parse links to .md files and add them to the build.
63m2r_parse_relative_links = True
64
65# The theme to use for HTML and HTML Help pages.  See the documentation for
66# a list of builtin themes.
67html_theme = 'sphinx_rtd_theme'
68
69# Add any paths that contain custom themes here, relative to this directory.
70html_theme_path = [
71    '_themes',
72]
73
74html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
75
76# The name for this set of Sphinx documents.  If None, it defaults to
77# "<project> v<release> documentation".
78html_title = 'Pigweed'
79
80# If true, SmartyPants will be used to convert quotes and dashes to
81# typographically correct entities.
82html_use_smartypants = True
83
84# If false, no module index is generated.
85html_domain_indices = True
86
87# If false, no index is generated.
88html_use_index = True
89
90# If true, the index is split into individual pages for each letter.
91html_split_index = False
92
93# If true, links to the reST sources are added to the pages.
94html_show_sourcelink = False
95
96# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
97html_show_sphinx = False
98
99# Output file base name for HTML help builder.
100htmlhelp_basename = 'Pigweeddoc'
101
102# One entry per manual page. List of tuples
103# (source start file, name, description, authors, manual section).
104man_pages = [('index', 'pigweed', 'Pigweed', ['Google'], 1)]
105
106# Grouping the document tree into Texinfo files. List of tuples
107# (source start file, target name, title, author,
108#  dir menu entry, description, category)
109texinfo_documents = [
110    ('index', 'Pigweed', 'Pigweed', 'Google', 'Pigweed', 'Firmware framework',
111     'Miscellaneous'),
112]
113
114# Markdown files imported using m2r aren't marked as "referenced," so exclude
115# them from the error reference checking.
116exclude_patterns = ['README.md']
117
118
119def do_not_skip_init(app, what, name, obj, would_skip, options):
120    if name == "__init__":
121        return False  # never skip __init__ functions
122
123    return would_skip
124
125
126def setup(app):
127    app.connect("autodoc-skip-member", do_not_skip_init)
128