Debian Codegraph @

doc/source/conf.py

raw
1 # -*- coding: utf-8 -*-
2 #
3 # Modules documentation build configuration file, created by
4 # sphinx-quickstart on Mon Oct 2 06:17:09 2017.
5 #
6 # This file is execfile()d with the current directory set to its
7 # containing dir.
8 #
9 # Note that not all possible configuration values are present in this
10 # autogenerated file.
11 #
12 # All configuration values have a default; values that are commented out
13 # serve to show the default.
14
15 # If extensions (or modules to document with autodoc) are in another directory,
16 # add these directories to sys.path here. If the directory is relative to the
17 # documentation root, use os.path.abspath to make it absolute, like shown here.
18 #
19 import os
20 import sys
21 # sys.path.insert(0, os.path.abspath('.'))
22
23
24 # -- General configuration ------------------------------------------------
25
26 # If your documentation needs a minimal Sphinx version, state it here.
27 #
28 needs_sphinx = '1.0'
29
30 # Add any Sphinx extension module names here, as strings. They can be
31 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32 # ones.
33 extensions = []
34
35 # Add any paths that contain templates here, relative to this directory.
36 templates_path = ['_templates']
37
38 # The suffix(es) of source filenames.
39 # You can specify multiple suffix as a list of string:
40 #
41 # source_suffix = ['.rst', '.md']
42 source_suffix = '.rst'
43
44 # The master toctree document.
45 master_doc = 'index'
46
47 # General information about the project.
48 project = u'Modules'
49 author = 'Modules Contributors'
50 copyright = f'1996-2025, {author}'
51
52 # The version info for the project you're documenting, acts as replacement for
53 # |version| and |release|, also used in various other places throughout the
54 # built documents.
55
56 from subprocess import Popen, PIPE
57 def get_version_release_from_git():
58 """
59 Returns project version and release as string from 'git' repository data.
60 """
61 DEVNULL = open(os.devnull, 'w')
62 pipe = Popen('git describe --tags --abbrev=0', stdout=PIPE, stderr=DEVNULL, shell=True, universal_newlines=True)
63 git_current_tag = pipe.stdout.read()
64 pipe = Popen('git describe --tags', stdout=PIPE, stderr=DEVNULL, shell=True, universal_newlines=True)
65 git_current_desc = pipe.stdout.read()
66 pipe = Popen('git rev-parse --abbrev-ref HEAD', stdout=PIPE, stderr=DEVNULL, shell=True, universal_newlines=True)
67 git_current_branch = pipe.stdout.read()
68
69 if git_current_desc:
70 version = git_current_tag.lstrip('v').rstrip()
71 if git_current_tag == git_current_desc:
72 return version, ''
73 else:
74 branch = git_current_branch.rstrip()
75 tags = git_current_desc.lstrip(git_current_tag + '-').rstrip()
76 # workaround for RTD, where main branch is not detected
77 if branch == 'main' or os.environ.get('READTHEDOCS', None) == 'True':
78 return version, version + '+' + tags
79 else:
80 return version, version + '+' + branch + '-' + tags
81 else:
82 return '5.6.1', ''
83
84 # The short X.Y version.
85 # The full version, including alpha/beta/rc tags.
86 if os.access('version.py', os.R_OK):
87 # get version and release information from version.py file
88 exec(open('version.py').read())
89 else:
90 # or fetch them from git repository data
91 version, release = get_version_release_from_git()
92
93 today_fmt = '%Y-%m-%d'
94
95 # The language for content autogenerated by Sphinx. Refer to documentation
96 # for a list of supported languages.
97 #
98 # This is also used if you do content translation via gettext catalogs.
99 # Usually you set "language" from the command line for these cases.
100 language = 'en'
101
102 # List of patterns, relative to source directory, that match files and
103 # directories to ignore when looking for source files.
104 # This patterns also effect to html_static_path and html_extra_path
105 exclude_patterns = []
106
107 # The name of the Pygments (syntax highlighting) style to use.
108 pygments_style = 'sphinx'
109
110 # If true, `todo` and `todoList` produce output, else they produce nothing.
111 todo_include_todos = False
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 os_rtd = os.environ.get('READTHEDOCS', None) == 'True'
120 if os_rtd:
121 html_theme = 'furo'
122 else:
123 html_theme = 'bizstyle'
124
125 # colorize terminal output
126 # handle large table
127 html_css_files = [
128 'literal_block.css',
129 'terminal_output.css',
130 ]
131
132 # Theme options are theme-specific and customize the look and feel of a theme
133 # further. For a list of options available for each theme, see the
134 # documentation.
135 #
136 # html_theme_options = {}
137 if os_rtd:
138 html_theme_options = {
139 'sidebar_hide_name': True,
140 'light_logo': 'modules_red.svg',
141 'dark_logo': 'modules_red.svg',
142 }
143
144 # The name of an image file (relative to this directory) to place at the top
145 # of the sidebar.
146 if not os_rtd:
147 html_logo = '_static/modules_red.svg'
148
149 # The name of an image file (within the static path) to use as favicon of the
150 # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
151 # pixels large.
152 html_favicon = '_static/favicon.ico'
153
154 # Add any paths that contain custom static files (such as style sheets) here,
155 # relative to this directory. They are copied after the builtin static files,
156 # so a file named "default.css" will overwrite the builtin "default.css".
157 html_static_path = ['_static']
158
159 # ensure quotes and dashes are preserved and not converted to lang-specific
160 # entities (fix issue#250). done by disabling `html_use_smartypants` on Sphinx
161 # version older than 1.6 and by disabling `smartquotes` on newer versions.
162 from sphinx import __version__ as sphinx_version
163 sphinx_version_parts = [int(i) for i in sphinx_version.split('.')]
164 if sphinx_version_parts[0] <= 1 and sphinx_version_parts[1] < 6:
165 html_use_smartypants = False
166 else:
167 smartquotes = False
168
169 # -- Options for HTMLHelp output ------------------------------------------
170
171 # Output file base name for HTML help builder.
172 htmlhelp_basename = 'Modulesdoc'
173
174
175 # -- Options for LaTeX output ---------------------------------------------
176
177 latex_elements = {
178 # The paper size ('letterpaper' or 'a4paper').
179 #
180 # 'papersize': 'letterpaper',
181
182 # The font size ('10pt', '11pt' or '12pt').
183 #
184 # 'pointsize': '10pt',
185
186 # Additional stuff for the LaTeX preamble.
187 #
188 # 'preamble': '',
189
190 # Latex figure (float) alignment
191 #
192 # 'figure_align': 'htbp',
193 }
194
195 # Grouping the document tree into LaTeX files. List of tuples
196 # (source start file, target name, title,
197 # author, documentclass [howto, manual, or own class]).
198 latex_documents = [
199 ('latex_index', 'modules.tex', f'{project} documentation', author, 'manual'),
200 ]
201
202
203 # replace locations by pattern to pre-generate pages in dist
204 if 'pathsubs' in tags:
205 prefix = '@prefix@'
206 bindir = '@bindir@'
207 libdir = '@libdir@'
208 libexecdir = '@libexecdir@'
209 etcdir = '@etcdir@'
210 initdir = '@initdir@'
211 modulefilesdir = '@modulefilesdir@'
212 # or set default distributions location
213 else:
214 prefix = '/usr/share/Modules'
215 bindir = prefix + '/bin'
216 libdir = prefix + '/lib64'
217 libexecdir = prefix + '/libexec'
218 etcdir = '/etc/environment-modules'
219 initdir = prefix + '/init'
220 modulefilesdir = prefix + '/modulefiles'
221
222 rst_epilog = '\n'
223 rst_epilog += '.. |prefix| replace:: %s\n' % prefix
224 rst_epilog += '.. |emph prefix| replace:: *%s*\n' % prefix
225 rst_epilog += '.. |bold prefix| replace:: **%s**\n' % prefix
226 rst_epilog += '.. |file prefix| replace:: :file:`%s`\n' % prefix
227 rst_epilog += '.. |bindir| replace:: %s\n' % bindir
228 rst_epilog += '.. |emph bindir| replace:: *%s*\n' % bindir
229 rst_epilog += '.. |bold bindir| replace:: **%s**\n' % bindir
230 rst_epilog += '.. |libdir| replace:: %s\n' % libdir
231 rst_epilog += '.. |file libdir_tcl_ext_lib| replace:: :file:`%s/libtclenvmodules.so`\n' % libdir
232 rst_epilog += '.. |libexecdir| replace:: %s\n' % libexecdir
233 rst_epilog += '.. |emph libexecdir| replace:: *%s*\n' % libexecdir
234 rst_epilog += '.. |bold libexecdir| replace:: **%s**\n' % libexecdir
235 rst_epilog += '.. |file libexecdir| replace:: :file:`%s`\n' % libexecdir
236 rst_epilog += '.. |file libexecdir_modulecmd| replace:: :file:`%s/modulecmd.tcl`\n' % libexecdir
237 rst_epilog += '.. |etcdir| replace:: %s\n' % etcdir
238 rst_epilog += '.. |emph etcdir| replace:: *%s*\n' % etcdir
239 rst_epilog += '.. |bold etcdir| replace:: **%s**\n' % etcdir
240 rst_epilog += '.. |file etcdir| replace:: :file:`%s`\n' % etcdir
241 rst_epilog += '.. |file etcdir_rc| replace:: :file:`%s/rc`\n' % etcdir
242 rst_epilog += '.. |file etcdir_siteconfig| replace:: :file:`%s/siteconfig.tcl`\n' % etcdir
243 rst_epilog += '.. |file etcdir_initrc| replace:: :file:`%s/initrc`\n' % etcdir
244 rst_epilog += '.. |file etcdir_modulespath| replace:: :file:`%s/modulespath`\n' % etcdir
245 rst_epilog += '.. |initdir| replace:: %s\n' % initdir
246 rst_epilog += '.. |emph initdir| replace:: *%s*\n' % initdir
247 rst_epilog += '.. |bold initdir| replace:: **%s**\n' % initdir
248 rst_epilog += '.. |file initdir_shell| replace:: :file:`%s/<shell>`\n' % initdir
249 rst_epilog += '.. |file initdir_csh| replace:: :file:`%s/csh`\n' % initdir
250 rst_epilog += '.. |modulefilesdir| replace:: %s\n' % modulefilesdir
251 rst_epilog += '.. |emph modulefilesdir| replace:: *%s*\n' % modulefilesdir
252 rst_epilog += '.. |bold modulefilesdir| replace:: **%s**\n' % modulefilesdir
253 rst_epilog += '.. |file modulefilesdir| replace:: :file:`%s`\n' % modulefilesdir
254 rst_epilog += '.. |code version| replace:: ``%s``\n' % version
255 rst_epilog += '.. |gh_tgz_dl_url| replace:: https://github.com/envmodules/modules/releases/download/v%s/modules-%s.tar.gz\n' % (version, version)
256
257 # define roles used to color text in parsed-literal to render output like in terminal
258 rst_epilog += """.. role:: noparse
259 .. role:: ps
260 .. role:: sgrb
261 .. role:: sgra
262 .. role:: sgrhi
263 .. role:: sgrer
264 .. role:: sgrwa
265 .. role:: sgrin
266 .. role:: sgrtr
267 .. role:: sgrse
268 .. role:: sgrcm
269 .. role:: sgrme
270 .. role:: sgrmp
271 .. role:: sgrdi
272 .. role:: sgrali
273 .. role:: sgrva
274 .. role:: sgrsy
275 .. role:: sgrde
276 .. role:: sgrh
277 .. role:: sgral
278 .. role:: sgrl
279 .. role:: sgrf
280 .. role:: sgrnf
281 .. role:: sgrs
282 .. role:: sgrshi
283 .. role:: sgrss
284 .. role:: sgrkl
285 .. role:: sgrvade
286 .. role:: sgrvahi
287 .. role:: sgrvadehi"""
288
289
290 # -- Options for manual page output ---------------------------------------
291
292 # One entry per manual page. List of tuples
293 # (source start file, name, description, authors, manual section).
294 man_pages = [
295 ('module', 'module', u'command interface to the Modules package', [], 1),
296 ('ml', 'ml', u'handy command interface to the Modules package', [], 1),
297 ('modulefile', 'modulefile', u'files containing Tcl code for the Modules package', [], 5),
298 ('envml', 'envml', u'run a command in an environment setting up by Modules', [], 1)
299 ]
300
301
302 # -- Options for Texinfo output -------------------------------------------
303
304 # Grouping the document tree into Texinfo files. List of tuples
305 # (source start file, target name, title, author,
306 # dir menu entry, description, category)
307 texinfo_documents = [
308 ]
309
310
311 # -- Options for linkcheck ------------------------------------------------
312
313 linkcheck_ignore = [
314 'https://matrix.to/#',
315 'module.html#version-specifiers',
316 'tag:S,F',
317 'tag:sticky',
318 ]
319 linkcheck_timeout = 5
320 linkcheck_workers = 1
321
322
323 # -- Extension interface --------------------------------------------------
324
325 from sphinx import addnodes
326 def parse_cmd_args_node(env, sig, signode):
327 try:
328 cmd, args = sig.strip().split(' ', 1)
329 except ValueError:
330 cmd, args = sig, None
331 # distinguish cmd from its args
332 signode += addnodes.desc_name(cmd, cmd)
333 if args:
334 args = ' ' + args
335 signode += addnodes.desc_addname(args, args)
336 return cmd
337
338 def parse_opt_args_node(env, sig, signode):
339 if (sig.strip().find('=') != -1):
340 sep = '='
341 else:
342 sep = ', '
343 try:
344 opt, args = sig.strip().split(sep, 1)
345 except ValueError:
346 opt, args = sig, None
347 # distinguish opt from its args
348 signode += addnodes.desc_name(opt, opt)
349 if args:
350 args = sep + args
351 signode += addnodes.desc_addname(args, args)
352 return opt
353
354 from docutils import nodes
355 def ghcommit_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
356 commit_id = str(text)
357 commit_url = 'https://github.com/envmodules/modules/commit/' + commit_id
358 title = nodes.reference('', commit_id, refuri=commit_url)
359 return [title], []
360
361 def setup(app):
362 # define new directive/role that can be used as .. subcmd::/:subcmd:,
363 # .. mfcmd::/:mfcmd:, .. mfvar::/:mfvar: and .. sitevar::/:sitevar:
364 app.add_object_type('subcmd', 'subcmd',
365 objname='module sub-command',
366 indextemplate='pair: %s; module sub-command',
367 parse_node=parse_cmd_args_node)
368 app.add_object_type(directivename='mfcmd', rolename='mfcmd',
369 objname='modulefile command',
370 indextemplate='pair: %s; modulefile command',
371 parse_node=parse_cmd_args_node)
372 app.add_object_type(directivename='mfvar', rolename='mfvar',
373 objname='modulefile variable',
374 indextemplate='pair: %s; modulefile variable',
375 parse_node=parse_cmd_args_node)
376 app.add_object_type(directivename='sitevar', rolename='sitevar',
377 objname='siteconfig variable',
378 indextemplate='pair: %s; siteconfig variable',
379 parse_node=parse_cmd_args_node)
380 app.add_object_type('instopt', 'instopt',
381 objname='installation option',
382 indextemplate='pair: %s; installation option',
383 parse_node=parse_opt_args_node)
384 app.add_object_type('mconfig', 'mconfig',
385 objname='module configuration option',
386 indextemplate='pair: %s; module configuration option')
387 app.add_role('ghcommit', ghcommit_role)
388
389 # exclude latex index document on non-latex output builder
390 def on_builder_inited(app):
391 if app.builder.name != 'latex':
392 app.config.exclude_patterns.append('latex_index.rst')
393
394 app.connect('builder-inited', on_builder_inited)