fork/fish-shell

git clone https://git.julia.blue/fork/fish-shell

Nahorman-pages: force encoding when reading doc sourcesf0054336e

master
9.3 KiB304 linesraw
1# -*- coding: utf-8 -*-
2#
3# Configuration file for the Sphinx documentation builder.
4#
5# This file only contains a selection of the most common options. For a full
6# list see the documentation:
7# https://www.sphinx-doc.org/en/master/usage/configuration.html
8
9from glob import glob
10import os.path
11import subprocess
12import sys
13from pathlib import Path
14from sphinx.highlighting import lexers
15from sphinx.errors import SphinxWarning
16from docutils import nodes
17
18try:
19    import sphinx_markdown_builder
20
21    extensions = [
22        "sphinx_markdown_builder",
23    ]
24except ImportError:
25    pass
26
27# -- Helper functions --------------------------------------------------------
28
29
30# A :issue: role to link to github issues.
31# Used like :issue:`2364`
32def issue_role(name, rawtext, text, lineno, inliner, options=None, content=None):
33    options = options or {}
34    try:
35        issue_num = int(text.strip())
36        if issue_num <= 0:
37            raise ValueError
38    except ValueError:
39        msg = inliner.reporter.error('Invalid issue number: "%s"' % text, line=lineno)
40        prb = inliner.problematic(rawtext, rawtext, msg)
41        return [prb], [msg]
42    template = issue_url + "/{n}"
43    ref = template.format(n=issue_num)
44    issue_text = "#{issue_no}".format(issue_no=issue_num)
45    link = nodes.reference(text=issue_text, refuri=ref, **options)
46    return [link], []
47
48
49def extract_sections(app, env):
50    if app.builder.name != "man":
51        return
52    output_file = app.config.fish_help_sections_output
53    if output_file == "":
54        return
55
56    import re
57
58    sections = []
59    for docname, info in env.tocs.items():
60        for node in info.traverse():
61            if not isinstance(node, nodes.reference):
62                continue
63            anchor = node["anchorname"]
64            if re.match(r"^#id\d+$", anchor):
65                continue
66            if anchor and docname.startswith("cmds/"):
67                continue
68            if anchor and docname == "relnotes":
69                continue
70            sections.append(docname + anchor)
71    sections.sort()
72    for section in sections:
73        assert re.match(r"[\w-]", section), (
74            f"Unsupported characters in section path: {section}"
75        )
76    help_sections = "".join(f"{section}\n" for section in sections)
77    Path(output_file).write_text(help_sections)
78
79
80def remove_fish_indent_lexer(app):
81    if app.builder.name in ("man", "markdown"):
82        del lexers["fish-docs-samples"]
83
84
85# -- Load our extensions -------------------------------------------------
86def setup(app):
87    # Our own pygments lexers
88    this_dir = os.path.dirname(os.path.realpath(__file__))
89    sys.path.insert(0, this_dir)
90    from fish_indent_lexer import FishIndentLexer
91    from fish_synopsis import FishSynopsisDirective, FishSynopsisLexer
92
93    lexers["fish-docs-samples"] = FishIndentLexer()
94    lexers["fish-synopsis"] = FishSynopsisLexer()
95    app.add_directive("synopsis", FishSynopsisDirective)
96
97    app.add_config_value("issue_url", default=None, rebuild="html")
98    app.add_config_value(
99        "fish_help_sections_output",
100        default="",
101        rebuild="man",
102        types=str,
103    )
104    app.add_role("issue", issue_role)
105
106    app.connect("builder-inited", remove_fish_indent_lexer)
107    app.connect("env-updated", extract_sections)
108
109
110# The default language to assume
111highlight_language = "fish-docs-samples"
112
113# -- Project information -----------------------------------------------------
114
115project = "fish-shell"
116copyright = "fish-shell developers"
117author = "fish-shell developers"
118issue_url = "https://github.com/fish-shell/fish-shell/issues"
119
120# From Cargo, or no build system.
121ret = subprocess.check_output(
122    ("../build_tools/git_version_gen.sh"), stderr=subprocess.STDOUT
123).decode("utf-8")
124
125# The full version, including alpha/beta/rc tags
126release = ret.strip().split(" ")[-1]
127# The short X.Y version
128version = release.rsplit(".", 1)[0]
129
130
131# -- General configuration ---------------------------------------------------
132
133# The suffix(es) of source filenames.
134# You can specify multiple suffix as a list of string:
135#
136# source_suffix = ['.rst', '.md']
137source_suffix = ".rst"
138
139# The master toctree document.
140master_doc = "index"
141
142# The languages this uses, also used for content autogenerated by Sphinx.
143#
144# This is also used if you do content translation via gettext catalogs.
145# Usually you set "language" from the command line for these cases.
146#
147# It also sets the html lang= attribute which would be useful to e.g. screenreaders.
148# Currently we only have english.
149language = "en"
150
151# List of patterns, relative to source directory, that match files and
152# directories to ignore when looking for source files.
153# This pattern also affects html_static_path and html_extra_path.
154fish_exclude_patterns = "cmds/*.inc.rst"
155exclude_patterns = [fish_exclude_patterns]
156
157# The name of the Pygments (syntax highlighting) style to use.
158pygments_style = None
159
160
161# -- Options for HTML output -------------------------------------------------
162
163# The theme to use for HTML and HTML Help pages.  See the documentation for
164# a list of builtin themes.
165# !!! If you change this you also need to update the @import at the top
166# of _static/pygments.css
167html_theme_path = ["."]
168html_theme = "python_docs_theme"
169
170# Shared styles across all doc versions.
171html_css_files = []
172
173# Don't add a weird "_sources" directory
174html_copy_source = False
175
176# Custom sidebar templates, must be a dictionary that maps document names
177# to template names.
178#
179# The default sidebars (for documents that don't match any pattern) are
180# defined by theme itself.  Builtin themes are using these templates by
181# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
182# 'searchbox.html']``.
183#
184html_sidebars = {"**": ["globaltoc.html", "searchbox.html", "localtoc.html"]}
185
186
187# -- Options for LaTeX output ------------------------------------------------
188
189# The default font is "GNU FreeSans" or something which I've never heard of.
190# Make this something that might actually be installed.
191latex_elements = {
192    "fontpkg": r"""
193    \setmainfont{Noto Serif}
194    \setsansfont{Noto Sans}
195    \setmonofont{Noto Sans Mono}
196    """,
197}
198
199# Grouping the document tree into LaTeX files. List of tuples
200# (source start file, target name, title,
201#  author, documentclass [howto, manual, or own class]).
202latex_documents = [
203    (
204        master_doc,
205        "fish-shell.tex",
206        "fish-shell Documentation",
207        "fish-shell developers",
208        "manual",
209    ),
210]
211
212# The default pdflatex doesn't handle unicode.
213# Switch to an engine that does (why pdflatex still exists and is still the default? I don't know)
214latex_engine = "xelatex"
215
216# -- Options for manual page output ------------------------------------------
217
218
219def get_command_description(path, name):
220    """Return the description for a command, by parsing its synopsis line"""
221    with open(path, encoding="utf8") as opened:
222        for line in opened:
223            if line.startswith(name + " - "):
224                _, desc = line.split(" - ", 1)
225                return desc.strip()
226            elif line.startswith("``" + name + "`` - "):
227                _, desc = line.split("`` - ", 1)
228                return desc.strip("`")
229    raise SphinxWarning("No description in file %s" % os.path.basename(path))
230
231
232# Newer sphinxen apparently create another subdirectory which breaks our man lookup.
233# Unbreak it (#7996)
234man_make_section_directory = False
235
236man_show_urls = True
237
238# One entry per manual page. List of tuples
239# (source start file, name, description, authors, manual section).
240man_pages = [
241    (master_doc, "fish-doc", "", [author], 1),
242    ("tutorial", "fish-tutorial", "", [author], 1),
243    ("language", "fish-language", "", [author], 1),
244    ("interactive", "fish-interactive", "", [author], 1),
245    ("relnotes", "fish-releasenotes", "", [author], 1),
246    ("terminal-compatibility", "fish-terminal-compatibility", "", [author], 1),
247    ("completions", "fish-completions", "", [author], 1),
248    ("prompt", "fish-prompt-tutorial", "", [author], 1),
249    (
250        "fish_for_bash_users",
251        "fish-for-bash-users",
252        "",
253        [author],
254        1,
255    ),
256    ("faq", "fish-faq", "", [author], 1),
257]
258for path in sorted(set(glob("cmds/*.rst")) - set(glob(fish_exclude_patterns))):
259    docname = os.path.splitext(path)[0]
260    cmd = os.path.basename(docname)
261    man_pages.append((docname, cmd, get_command_description(path, cmd), "", 1))
262
263
264# -- Options for Texinfo output ----------------------------------------------
265
266# Grouping the document tree into Texinfo files. List of tuples
267# (source start file, target name, title, author,
268#  dir menu entry, description, category)
269texinfo_documents = [
270    (
271        master_doc,
272        "fish-shell",
273        "fish-shell Documentation",
274        author,
275        "fish-shell",
276        "the friendly interactive shell",
277        "Miscellaneous",
278    )
279]
280
281
282# -- Options for Epub output -------------------------------------------------
283
284# Bibliographic Dublin Core info.
285epub_title = project
286
287# The unique identifier of the text. This can be a ISBN number
288# or the project homepage.
289#
290# epub_identifier = ''
291
292# A unique identification for the text.
293#
294# epub_uid = ''
295
296# A list of files that should not be packed into the epub file.
297epub_exclude_files = ["search.html"]
298
299# Enable smart-quotes
300# default action is 'qDe': quotes, Dashes, ellipsis. Skip dashes for --options
301smartquotes = True
302smartquotes_action = "qe"
303
304linkcheck_ignore = [r"https://github.com/fish-shell/fish-shell/issues/\d+"]