forked from cylc/cylc-doc
-
Notifications
You must be signed in to change notification settings - Fork 0
/
conf.py
299 lines (245 loc) · 9.13 KB
/
conf.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
# THIS FILE IS PART OF THE CYLC WORKFLOW ENGINE.
# Copyright (C) NIWA & British Crown (Met Office) & Contributors.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
from distutils.spawn import find_executable as which
import os
from pathlib import Path
import sys
from cylc.flow import __version__ as CYLC_VERSION
from cylc.flow.workflow_files import WorkflowFiles
sys.path.append(os.path.abspath('lib')) # path to lib.
from cylc_release import CYLC_RELEASE
# -- General configuration ------------------------------------------------
# Sphinx extension module names.
sys.path.append(os.path.abspath('ext')) # path to custom extensions.
extensions = [
# sphinx built-in extensions
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.graphviz',
'sphinx.ext.intersphinx',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
'sphinxcontrib.spelling',
# sphinx user community extensions
'hieroglyph',
'sphinx_rtd_theme',
'sphinx_design',
# custom project extensions (located in ext/)
'autodoc_traits', # autodoc uiserver traitlets
'database_diagram',
'autodoc_enum_values',
# cylc-sphinx-extensions
'cylc.sphinx_ext.cylc_lang',
'cylc.sphinx_ext.diff_selection',
'cylc.sphinx_ext.grid_table',
'cylc.sphinx_ext.hieroglyph_addons',
'cylc.sphinx_ext.minicylc',
'cylc.sphinx_ext.practical',
'cylc.sphinx_ext.rtd_theme_addons',
'cylc.sphinx_ext.sub_lang',
'cylc.sphinx_ext.literal_sub_include'
]
# Can define substitutions in prolog/epilog:
rst_prolog = f"""
.. |reserved_filenames| replace:: ``{'``, ``'.join(WorkflowFiles.RESERVED_NAMES)}``
"""
rst_epilog = open('hyperlinks.rst.include', 'r').read()
default_role = 'cylc:conf'
# Select best available SVG image converter.
for svg_converter, extension in [
('rsvg', 'sphinxcontrib.rsvgconverter'),
('inkscape', 'sphinxcontrib.inkscapeconverter')]:
if which(svg_converter):
try:
__import__(extension)
except (AssertionError, ImportError):
# converter or extension not available
pass
else:
extensions.append(extension)
break
else:
# no extensions or converters available, fall-back to default
# vector graphics will be converted to bitmaps in all documents
extensions.append('sphinx.ext.imgconverter')
# Add any paths that contain templates.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'Cylc'
__copyright_year = 2024 # NOTE: this is automatically set by GH Actions
copyright = (
f'2008-{__copyright_year} NIWA & British Crown (Met Office) & Contributors'
)
# Versioning information.
# NOTE: Sphinx considers version/release the other way around to us
release = CYLC_VERSION # full version e.g. "8.0.0"
version = CYLC_RELEASE # short version (for pinning / display) e.g. "8.0"
# Autosummary opts (for auto generation of docs from source code).
autosummary_generate = True
autosummary_generate_overwrite = True
autosummary_imported_members = False
# Autodoc type hints can look very messy if they are included in the signature,
# so we only include them in the description instead:
autodoc_typehints = 'description'
# Mapping to other Sphinx projects we want to import references from.
# NOTE: To search available references, use:
# $ python -m sphinx.ext.intersphinx <url>/objects.inv | less
intersphinx_mapping = {
'rose': (
'http://metomi.github.io/rose/2.1.0/html', None
),
'python': (
'https://docs.python.org/3/', None
),
'jupyter_server': (
'https://jupyter-server.readthedocs.io/en/latest/', None
),
'jupyter_hub': (
'https://jupyterhub.readthedocs.io/en/stable/', None
)
}
nitpick_ignore = [
# This class appears in documented type-hints but is not documented in the
# Python docs so fails build.
('py:class', 're.Pattern'),
('py:class', 'SubFuncContext'),
('py:exc', 'ISO8601SyntaxError'),
('py:exc', 'StrftimeSyntaxError'),
]
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# exclude_patterns = ['_build']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'autumn'
# Global configuration for graphviz diagrams.
graphviz_output_format = 'svg'
graphviz_dot_args = ['-Gfontname=sans', '-Gbgcolor=none',
'-Nfontname=sans']
linkcheck_ignore = [
# linux.die.net doesn't like our request headers
'https?://linux.die.net/man/1/bash',
# linkcheck has trouble handling GH anchors
'https?://github.com/.*#.*',
]
nitpick_ignore_regex = [
# intersphinx has trouble with pyzmq classes:
('py:class', 'zmq\.asyncio\.\w ')
]
# -- Options for Slides output ----------------------------------------------
slide_theme = 'single-level'
slide_link_to_html = True
slide_theme_options = {'custom_css': 'css/slides-custom.css'}
# -- Options for HTML output ----------------------------------------------
# Theme
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
'logo_only': True,
'navigation_depth': 4
}
html_logo = "img/cylc-logo-white.svg"
html_favicon = "img/cylc-favicon.ico" # sphinx specifies .ico format
html_show_sphinx = False
html_show_copyright = True
# Custom sidebar templates, maps document names to template names.
html_sidebars = {
'**': [
'globaltoc.html',
'searchbox.html',
'sourcelink.html',
'versions.html'
],
}
# Values to pass into the templating context. Can be overridden using the
# sphinx-build opt `-A name=value` (add to SPHINXOPTS if using make).
html_context = {
'sidebar_version_name': None, # override name in version picker
}
html_static_path = ['_static']
# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = ['css/custom.css']
# Disable timestamp otherwise inserted at bottom of every page.
html_last_updated_fmt = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'cylcdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
'papersize': 'a4paper',
'pointsize': '11pt',
}
# Title for the cylc documentation section
CYLC_DOC_TITLE = 'Cylc Documentation'
# 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 = [
('index', 'cylc.tex', CYLC_DOC_TITLE, copyright, 'manual'),
]
# Image file to place at the top of the title page.
latex_logo = "img/cylc-logo-greyscale.svg"
# If true, show URL addresses after external links.
latex_show_urls = "footnote"
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'cylc', CYLC_DOC_TITLE, copyright, 1),
]
# If true, show URL addresses after external links.
man_show_urls = True
# -- 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)
texinfo_documents = [
('index', 'cylc', CYLC_DOC_TITLE, copyright, 'cylc', project,
'Miscellaneous'),
]
# How to display URL addresses.
texinfo_show_urls = 'footnote'
# Substitutions (e.g. |version|) to make when using literalsubinclude
literal_sub_include_subs = {
'version': version,
'release': release,
}
# Settings for spelling checks
# Proper nouns are words where we want to explicitly set the case, so
# include acronyms and proper names where we might want to explicitly set
# case lower, for example if we use it in scripts (e.g. "conda").
spelling_lang = 'en_NZ'
# for x in $(cat src/dictionaries/words);do echo ${x^};
# done > src/dictionaries/sentence_case
spelling_word_list_filename = [
'dictionaries/words',
'dictionaries/proper_nouns',
'dictionaries/sentence_case'
]
spelling_warning = True
spelling_verbose = True
dictionaries = Path.cwd() / 'dictionaries'
wordsfile = dictionaries / 'words'
sentence_case_file = dictionaries / 'sentence_case'
# Sort wordlist:
words = wordsfile.read_text().split('\n')
words = [w for w in sorted(words) if w]
wordsfile.write_text('\n'.join(words) '\n')
# Create sentence case versions of wordlist:
sentence_case = [word.capitalize() for word in words]
sentence_case_file.write_text('\n'.join(sentence_case) '\n')