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