Verilator

1
# pylint: disable=C0103,C0114,C0116,C0301,E0402,W0622
2
#
3
# Configuration file for Verilator's Sphinx documentation builder.
4
# Copyright 2003-2024 by Wilson Snyder.
5
# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
6
#
7
# This file only contains overridden options. For a full list:
8
# https://www.sphinx-doc.org/en/master/usage/configuration.html
9
#
10
# ----------------------------------------------------------------------
11
# -- Path setup
12

13
import os
14
import re
15
import sys
16

17
sys.path.insert(0, os.path.abspath('./_ext'))
18

19
import sphinx_rtd_theme  # pylint: disable=wrong-import-position,
20

21

22
def get_vlt_version():
23
    filename = "../../Makefile"
24
    with open(filename, "r", encoding="utf8") as fh:
25
        for line in fh:
26
            match = re.search(r"PACKAGE_VERSION *= *([a-z0-9.]+) +([-0-9]+)",
27
                              line)
28
            if match:
29
                return match.group(1), match.group(2)
30
            match = re.search(r"PACKAGE_VERSION *= *([a-z0-9.]+) +devel", line)
31
            if match:
32
                try:
33
                    data = os.popen('git log -n 1 --pretty=%cs').read()
34
                except Exception:  # pylint: disable=broad-except
35
                    data = ""  # fallback, and Sphinx will fill in today's date
36
                return "Devel " + match.group(1), data
37
    return "unknown", "unknown"
38

39

40
def setup(app):
41
    app.add_css_file('css/vlt_sphinx.css')
42

43

44
# ----------------------------------------------------------------------
45
# -- Project information
46

47
project = 'Verilator'
48
copyright = '2024 by Wilson Snyder, under LGPL-3.0 or Artistic-2.0'
49
author = 'Wilson Snyder'
50

51
# The master toctree document.
52
master_doc = "index"
53

54
version, today_fmt = get_vlt_version()
55
release = version
56

57
rst_prolog = """
58
.. role:: vlopt(option)
59
"""
60

61
# ----------------------------------------------------------------------
62
# -- General configuration
63

64
# Add any Sphinx extension module names here, as strings. They can be
65
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
66
# ones.
67
# To install:
68
#   sudo install enchant
69
#   sudo pip3 install sphinx sphinx_rtd_theme breathe sphinxcontrib-spelling
70
# We keep this list empty for now to avoid needing dependencies
71
extensions = []
72
# extensions = ['breathe', 'sphinxcontrib.spelling']
73

74
# List of patterns, relative to source directory, that match files and
75
# directories to ignore when looking for source files.
76
# This pattern also affects html_static_path and html_extra_path.
77
exclude_patterns = [
78
    '_build', 'Thumbs.db', '.DS_Store', 'internals.rst', 'xml.rst', 'gen/ex_*',
79
    'CONTRIBUTING.rst'
80
]
81

82
# Warn about refs
83
nitpicky = True
84
nitpicky_ignore = []
85

86
# Number figures for referencing
87
numfig = True
88

89
# The name of the Pygments (syntax highlighting) style to use.
90
pygments_style = "sphinx"
91

92
# The suffix(es) of source filenames.
93
# You can specify multiple suffix as a list of string:
94
source_suffix = [".rst"]
95

96
# Add any paths that contain templates here, relative to this directory.
97
templates_path = ['_templates']
98

99
# If true, `todo` and `todoList` produce output, else they produce nothing.
100
todo_include_todos = True
101

102
# Could use this for internals<->guide references
103
# intersphinx_mapping = { 'sphinx': ('https://sphinx-doc.org/', None), }
104

105
# ----------------------------------------------------------------------
106
# -- Options for HTML output
107

108
# html_baseurl =
109

110
html_domain_indices = False
111

112
html_logo = "../_static/verilator_192_150_min.png"
113

114
html_theme = 'sphinx_rtd_theme'
115
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
116

117
html_theme_options = {
118
    'logo_only': True,
119
    'style_nav_header_background': "#45acf8",  # Default is #2980B9
120
    # 'canonical_url':
121
}
122

123
html_context = {
124
    'display_github': True,
125
    'github_user': 'verilator',
126
    'github_repo': 'verilator',
127
    'github_version': 'master/docs/guide/',
128
}
129

130
# Add any paths that contain custom static files (such as style sheets) here,
131
# relative to this directory. They are copied after the builtin static files,
132
# so a file named "default.css" will overwrite the builtin "default.css".
133
html_static_path = ['../_static']
134

135
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
136
html_show_sphinx = False
137

138
html_copy_source = False
139
html_show_sourcelink = False
140

141
html_use_index = False
142

143
html_favicon = "../_static/verilator_32x32_min.png"
144

145
# Custom sidebar templates, maps document names to template names.
146
# html_sidebars
147

148
# Add any extra paths that contain custom files (such as robots.txt or
149
# .htaccess) here, relative to this directory. These files are copied
150
# directly to the root of the documentation.
151
# html_extra_path = []
152

153
# Additional templates that should be rendered to pages, maps page names to
154
# template names.
155
# html_additional_pages = {}
156

157
# ----------------------------------------------------------------------
158
# -- Options for Latex output
159

160
latex_logo = "../_static/verilator_logo.png"
161

162
latex_elements = {
163
    'extraclassoptions': 'openany,oneside',
164
    'papersize': 'letterpaper',
165
    'makeindex': '',
166
    'printindex': '',
167
    # 'pointsize': '10pt',
168
    # 'preamble': '',
169
}
170

171
# Grouping the document tree into LaTeX files. List of tuples
172
# (source start file, target name, title,
173
#  author, documentclass [howto, manual, or own class]).
174
# latex_documents = [
175
#    (
176
#        master_doc,
177
#        "Verilog-to-Routing.tex",
178
#        "Verilog-to-Routing Documentation",
179
#        "VTR Developers",
180
#        "manual",
181
#    ),
182
# ]
183

184
# For "manual" documents, if this is true, then toplevel headings are parts,
185
# not chapters.
186
# latex_use_parts = False
187

188
# If true, show page references after internal links.
189
# latex_show_pagerefs = False
190

191
# If true, show URL addresses after external links.
192
# latex_show_urls = False
193

194
latex_domain_indices = False
195

196
# ----------------------------------------------------------------------
197
# -- Options for manual page output
198

199
# One entry per manual page. List of tuples
200
# (source start file, name, description, authors, manual section).
201
# man_pages = [(master_doc, "verilog-to-routing", "Verilog-to-Routing Documentation", [author], 1)]
202

203
# If true, show URL addresses after external links.
204
# man_show_urls = False
205

206
# ----------------------------------------------------------------------
207
# -- Options for spelling
208

209
spelling_word_list_filename = ['spelling.txt']
210
spelling_ignore_contributor_names = True
211

212
# ----------------------------------------------------------------------
213
# -- Options for doxygen
214

215
# if shutil.which("doxygen"):
216
#    breathe_projects = {
217
#        "verilated": "../_build/doxygen/verilated/xml",
218
#    }
219
#    breathe_default_project = "verilated"
220
#
221
#    if not os.environ.get("SKIP_DOXYGEN", None) == "True":
222
#        for prjname, prjdir in breathe_projects.items():
223
#            print("Generating doxygen files for {}...".format(prjname))
224
#            os.makedirs(prjdir, exist_ok=True)
225
#            cmd = "cd ../_doxygen && doxygen {}.dox".format(prjname)
226
#            subprocess.call(cmd, shell=True)
227
#    else:
228
#        for prjname, prjdir in breathe_projects.items():
229
#            assert os.path.exists(prjdir) == True, "Regenerate doxygen XML for {}".format(prjname)
230

231
breathe_projects = {"verilated": "_build/doxygen/verilated/xml/"}
232
breathe_default_project = "verilated"
233
breathe_default_members = 'members'
234