mirror of
https://github.com/kovidgoyal/kitty.git
synced 2024-10-26 15:13:22 +03:00
760 lines
28 KiB
Python
760 lines
28 KiB
Python
#!/usr/bin/env python
|
|
# vim:fileencoding=utf-8
|
|
#
|
|
# Configuration file for the Sphinx documentation builder.
|
|
#
|
|
# This file does only contain a selection of the most common options. For a
|
|
# full list see the documentation:
|
|
# https://www.sphinx-doc.org/en/master/config
|
|
|
|
import glob
|
|
import os
|
|
import re
|
|
import subprocess
|
|
import sys
|
|
import time
|
|
from functools import lru_cache, partial
|
|
from typing import Any, Callable, Dict, Iterable, Iterator, List, Tuple
|
|
|
|
from docutils import nodes
|
|
from docutils.parsers.rst.roles import set_classes
|
|
from pygments.lexer import RegexLexer, bygroups # type: ignore
|
|
from pygments.token import Comment, Error, Keyword, Literal, Name, Number, String, Whitespace # type: ignore
|
|
from sphinx import addnodes, version_info
|
|
from sphinx.util.logging import getLogger
|
|
|
|
kitty_src = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
|
if kitty_src not in sys.path:
|
|
sys.path.insert(0, kitty_src)
|
|
|
|
from kitty.conf.types import Definition, expand_opt_references # noqa
|
|
from kitty.constants import str_version, website_url # noqa
|
|
from kitty.fast_data_types import Shlex # noqa
|
|
|
|
# config {{{
|
|
# -- Project information -----------------------------------------------------
|
|
|
|
project = 'kitty'
|
|
copyright = time.strftime('%Y, Kovid Goyal')
|
|
author = 'Kovid Goyal'
|
|
building_man_pages = 'man' in sys.argv
|
|
|
|
# The short X.Y version
|
|
version = str_version
|
|
# The full version, including alpha/beta/rc tags
|
|
release = str_version
|
|
logger = getLogger(__name__)
|
|
|
|
|
|
# -- General configuration ---------------------------------------------------
|
|
|
|
# If your documentation needs a minimal Sphinx version, state it here.
|
|
#
|
|
needs_sphinx = '1.7'
|
|
|
|
# Add any Sphinx extension module names here, as strings. They can be
|
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
|
# ones.
|
|
extensions = [
|
|
'sphinx.ext.ifconfig',
|
|
'sphinx.ext.viewcode',
|
|
'sphinx.ext.githubpages',
|
|
'sphinx.ext.extlinks',
|
|
'sphinx_copybutton',
|
|
'sphinx_inline_tabs',
|
|
"sphinxext.opengraph",
|
|
]
|
|
|
|
# URL for OpenGraph tags
|
|
ogp_site_url = website_url()
|
|
# OGP needs a PNG image because of: https://github.com/wpilibsuite/sphinxext-opengraph/issues/96
|
|
ogp_social_cards = {
|
|
'image': '../logo/kitty.png'
|
|
}
|
|
|
|
# Add any paths that contain templates here, relative to this directory.
|
|
templates_path = ['_templates']
|
|
|
|
# The suffix(es) of source filenames.
|
|
# You can specify multiple suffix as a list of string:
|
|
#
|
|
# source_suffix = ['.rst', '.md']
|
|
source_suffix = '.rst'
|
|
|
|
# The master toctree document.
|
|
master_doc = 'index'
|
|
|
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
|
# for a list of supported languages.
|
|
#
|
|
# This is also used if you do content translation via gettext catalogs.
|
|
# Usually you set "language" from the command line for these cases.
|
|
language: str = 'en'
|
|
|
|
# List of patterns, relative to source directory, that match files and
|
|
# directories to ignore when looking for source files.
|
|
# This pattern also affects html_static_path and html_extra_path .
|
|
exclude_patterns = [
|
|
'_build', 'Thumbs.db', '.DS_Store', 'basic.rst',
|
|
'generated/cli-*.rst', 'generated/conf-*.rst', 'generated/actions.rst'
|
|
]
|
|
|
|
rst_prolog = '''
|
|
.. |kitty| replace:: *kitty*
|
|
.. |version| replace:: VERSION
|
|
.. _tarball: https://github.com/kovidgoyal/kitty/releases/download/vVERSION/kitty-VERSION.tar.xz
|
|
.. role:: italic
|
|
|
|
'''.replace('VERSION', str_version)
|
|
smartquotes_action = 'qe' # educate quotes and ellipses but not dashes
|
|
|
|
def go_version(go_mod_path: str) -> str: # {{{
|
|
with open(go_mod_path) as f:
|
|
for line in f:
|
|
if line.startswith('go '):
|
|
return line.strip().split()[1]
|
|
raise SystemExit(f'No Go version in {go_mod_path}')
|
|
# }}}
|
|
|
|
string_replacements = {
|
|
'_kitty_install_cmd': 'curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin',
|
|
'_build_go_version': go_version('../go.mod'),
|
|
}
|
|
|
|
|
|
# -- Options for HTML output -------------------------------------------------
|
|
|
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
|
# a list of builtin themes.
|
|
#
|
|
html_theme = 'furo'
|
|
html_title = 'kitty'
|
|
|
|
# Theme options are theme-specific and customize the look and feel of a theme
|
|
# further. For a list of options available for each theme, see the
|
|
# documentation.
|
|
github_icon_path = 'M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z' # noqa
|
|
|
|
html_theme_options: Dict[str, Any] = {
|
|
'sidebar_hide_name': True,
|
|
'navigation_with_keys': True,
|
|
'footer_icons': [
|
|
{
|
|
"name": "GitHub",
|
|
"url": "https://github.com/kovidgoyal/kitty",
|
|
"html": f"""
|
|
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
|
|
<path fill-rule="evenodd" d="{github_icon_path}"></path>
|
|
</svg>
|
|
""",
|
|
"class": "",
|
|
},
|
|
],
|
|
}
|
|
|
|
|
|
# Add any paths that contain custom static files (such as style sheets) here,
|
|
# relative to this directory. They are copied after the builtin static files,
|
|
# so a file named "default.css" will overwrite the builtin "default.css".
|
|
html_static_path = ['_static']
|
|
html_favicon = html_logo = '../logo/kitty.svg'
|
|
html_css_files = ['custom.css', 'timestamps.css']
|
|
html_js_files = ['custom.js', 'timestamps.js']
|
|
|
|
# Custom sidebar templates, must be a dictionary that maps document names
|
|
# to template names.
|
|
#
|
|
# The default sidebars (for documents that don't match any pattern) are
|
|
# defined by theme itself. Builtin themes are using these templates by
|
|
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
|
|
# 'searchbox.html']``.
|
|
#
|
|
html_show_sourcelink = False
|
|
html_show_sphinx = False
|
|
manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
|
|
|
|
# -- Options for manual page output ------------------------------------------
|
|
|
|
# One entry per manual page. List of tuples
|
|
# (source start file, name, description, authors, manual section).
|
|
man_pages = [
|
|
('invocation', 'kitty', 'The fast, feature rich terminal emulator', [author], 1),
|
|
('conf', 'kitty.conf', 'Configuration file for kitty', [author], 5)
|
|
]
|
|
|
|
|
|
# -- 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 = [
|
|
(master_doc, 'kitty', 'kitty Documentation',
|
|
author, 'kitty', 'Cross-platform, fast, feature-rich, GPU based terminal',
|
|
'Miscellaneous'),
|
|
]
|
|
# }}}
|
|
|
|
|
|
# GitHub linking inline roles {{{
|
|
|
|
extlinks = {
|
|
'iss': ('https://github.com/kovidgoyal/kitty/issues/%s', '#%s'),
|
|
'pull': ('https://github.com/kovidgoyal/kitty/pull/%s', '#%s'),
|
|
'disc': ('https://github.com/kovidgoyal/kitty/discussions/%s', '#%s'),
|
|
}
|
|
|
|
|
|
def commit_role(
|
|
name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []
|
|
) -> Tuple[List[nodes.reference], List[nodes.problematic]]:
|
|
' Link to a github commit '
|
|
try:
|
|
commit_id = subprocess.check_output(
|
|
f'git rev-list --max-count=1 {text}'.split()).decode('utf-8').strip()
|
|
except Exception:
|
|
msg = inliner.reporter.error(
|
|
f'git commit id "{text}" not recognized.', line=lineno)
|
|
prb = inliner.problematic(rawtext, rawtext, msg)
|
|
return [prb], [msg]
|
|
url = f'https://github.com/kovidgoyal/kitty/commit/{commit_id}'
|
|
set_classes(options)
|
|
short_id = subprocess.check_output(
|
|
f'git rev-list --max-count=1 --abbrev-commit {commit_id}'.split()).decode('utf-8').strip()
|
|
node = nodes.reference(rawtext, f'commit: {short_id}', refuri=url, **options)
|
|
return [node], []
|
|
# }}}
|
|
|
|
|
|
# CLI docs {{{
|
|
def write_cli_docs(all_kitten_names: Iterable[str]) -> None:
|
|
from kittens.ssh.main import copy_message, option_text
|
|
from kitty.cli import option_spec_as_rst
|
|
with open('generated/ssh-copy.rst', 'w') as f:
|
|
f.write(option_spec_as_rst(
|
|
appname='copy', ospec=option_text, heading_char='^',
|
|
usage='file-or-dir-to-copy ...', message=copy_message
|
|
))
|
|
del sys.modules['kittens.ssh.main']
|
|
|
|
from kitty.launch import options_spec as launch_options_spec
|
|
with open('generated/launch.rst', 'w') as f:
|
|
f.write(option_spec_as_rst(
|
|
appname='launch', ospec=launch_options_spec, heading_char='_',
|
|
message='''\
|
|
Launch an arbitrary program in a new kitty window/tab. Note that
|
|
if you specify a program-to-run you can use the special placeholder
|
|
:code:`@selection` which will be replaced by the current selection.
|
|
'''
|
|
))
|
|
with open('generated/cli-kitty.rst', 'w') as f:
|
|
f.write(option_spec_as_rst(appname='kitty').replace(
|
|
'kitty --to', 'kitty @ --to'))
|
|
as_rst = partial(option_spec_as_rst, heading_char='_')
|
|
from kitty.rc.base import all_command_names, command_for_name
|
|
from kitty.remote_control import cli_msg, global_options_spec
|
|
with open('generated/cli-kitten-at.rst', 'w') as f:
|
|
p = partial(print, file=f)
|
|
p('kitten @')
|
|
p('-' * 80)
|
|
p('.. program::', 'kitten @')
|
|
p('\n\n' + as_rst(
|
|
global_options_spec, message=cli_msg, usage='command ...', appname='kitten @'))
|
|
from kitty.rc.base import cli_params_for
|
|
for cmd_name in sorted(all_command_names()):
|
|
func = command_for_name(cmd_name)
|
|
p(f'.. _at-{func.name}:\n')
|
|
p('kitten @', func.name)
|
|
p('-' * 120)
|
|
p('.. program::', 'kitten @', func.name)
|
|
p('\n\n' + as_rst(*cli_params_for(func)))
|
|
from kittens.runner import get_kitten_cli_docs
|
|
|
|
for kitten in all_kitten_names:
|
|
data = get_kitten_cli_docs(kitten)
|
|
if data:
|
|
with open(f'generated/cli-kitten-{kitten}.rst', 'w') as f:
|
|
p = partial(print, file=f)
|
|
p('.. program::', 'kitty +kitten', kitten)
|
|
p('\nSource code for', kitten)
|
|
p('-' * 72)
|
|
scurl = f'https://github.com/kovidgoyal/kitty/tree/master/kittens/{kitten}'
|
|
p(f'\nThe source code for this kitten is `available on GitHub <{scurl}>`_.')
|
|
p('\nCommand Line Interface')
|
|
p('-' * 72)
|
|
p('\n\n' + option_spec_as_rst(
|
|
data['options'], message=data['help_text'], usage=data['usage'], appname=f'kitty +kitten {kitten}',
|
|
heading_char='^'))
|
|
|
|
# }}}
|
|
|
|
|
|
def write_remote_control_protocol_docs() -> None: # {{{
|
|
from kitty.rc.base import RemoteCommand, all_command_names, command_for_name
|
|
field_pat = re.compile(r'\s*([^:]+?)\s*:\s*(.+)')
|
|
|
|
def format_cmd(p: Callable[..., None], name: str, cmd: RemoteCommand) -> None:
|
|
p(name)
|
|
p('-' * 80)
|
|
lines = (cmd.__doc__ or '').strip().splitlines()
|
|
fields = []
|
|
for line in lines:
|
|
m = field_pat.match(line)
|
|
if m is None:
|
|
p(line)
|
|
else:
|
|
fields.append((m.group(1).split('/')[0], m.group(2)))
|
|
if fields:
|
|
p('\nFields are:\n')
|
|
for (name, desc) in fields:
|
|
if '+' in name:
|
|
title = name.replace('+', ' (required)')
|
|
else:
|
|
title = name
|
|
defval = cmd.get_default(name.replace('-', '_'), cmd)
|
|
if defval is not cmd:
|
|
title = f'{title} (default: {defval})'
|
|
else:
|
|
title = f'{title} (optional)'
|
|
p(f':code:`{title}`')
|
|
p(' ', desc), p()
|
|
p(), p()
|
|
|
|
with open('generated/rc.rst', 'w') as f:
|
|
p = partial(print, file=f)
|
|
for name in sorted(all_command_names()):
|
|
cmd = command_for_name(name)
|
|
if not cmd.__doc__:
|
|
continue
|
|
name = name.replace('_', '-')
|
|
format_cmd(p, name, cmd)
|
|
# }}}
|
|
|
|
|
|
def replace_string(app: Any, docname: str, source: List[str]) -> None: # {{{
|
|
src = source[0]
|
|
for k, v in app.config.string_replacements.items():
|
|
src = src.replace(k, v)
|
|
source[0] = src
|
|
# }}}
|
|
|
|
# config file docs {{{
|
|
|
|
|
|
class ConfLexer(RegexLexer): # type: ignore
|
|
name = 'Conf'
|
|
aliases = ['conf']
|
|
filenames = ['*.conf']
|
|
|
|
def map_flags(self: RegexLexer, val: str, start_pos: int) -> Iterator[Tuple[int, Any, str]]:
|
|
expecting_arg = ''
|
|
s = Shlex(val)
|
|
from kitty.options.utils import allowed_key_map_options
|
|
last_pos = 0
|
|
while (tok := s.next_word())[0] > -1:
|
|
x = tok[1]
|
|
if tok[0] > last_pos:
|
|
yield start_pos + last_pos, Whitespace, ' ' * (tok[0] - last_pos)
|
|
last_pos = tok[0] + len(x)
|
|
tok_start = start_pos + tok[0]
|
|
if expecting_arg:
|
|
yield tok_start, String, x
|
|
expecting_arg = ''
|
|
elif x.startswith('--'):
|
|
expecting_arg = x[2:]
|
|
k, sep, v = expecting_arg.partition('=')
|
|
k = k.replace('-', '_')
|
|
expecting_arg = k
|
|
if expecting_arg not in allowed_key_map_options:
|
|
yield tok_start, Error, x
|
|
elif sep == '=':
|
|
expecting_arg = ''
|
|
yield tok_start, Name, x
|
|
else:
|
|
yield tok_start, Name, x
|
|
else:
|
|
break
|
|
|
|
def mapargs(self: RegexLexer, match: 're.Match[str]') -> Iterator[Tuple[int, Any, str]]:
|
|
start_pos = match.start()
|
|
val = match.group()
|
|
parts = val.split(maxsplit=1)
|
|
if parts[0].startswith('--'):
|
|
seen = 0
|
|
for (pos, token, text) in self.map_flags(val, start_pos):
|
|
yield pos, token, text
|
|
seen += len(text)
|
|
start_pos += seen
|
|
val = val[seen:]
|
|
parts = val.split(maxsplit=1)
|
|
|
|
if not val:
|
|
return
|
|
yield start_pos, Literal, parts[0] # key spec
|
|
if len(parts) == 1:
|
|
return
|
|
start_pos += len(parts[0])
|
|
val = val[len(parts[0]):]
|
|
m = re.match(r'(\s+)(\S+)', val)
|
|
if m is None:
|
|
return
|
|
yield start_pos, Whitespace, m.group(1)
|
|
yield start_pos + m.start(2), Name.Function, m.group(2) # action function
|
|
yield start_pos + m.end(2), String, val[m.end(2):]
|
|
|
|
tokens = {
|
|
'root': [
|
|
(r'#.*?$', Comment.Single),
|
|
(r'\s+$', Whitespace),
|
|
(r'\s+', Whitespace),
|
|
(r'(include)(\s+)(.+?)$', bygroups(Comment.Preproc, Whitespace, Name.Namespace)),
|
|
(r'(map)(\s+)', bygroups(
|
|
Keyword.Declaration, Whitespace), 'mapargs'),
|
|
(r'(mouse_map)(\s+)(\S+)(\s+)(\S+)(\s+)(\S+)(\s+)', bygroups(
|
|
Keyword.Declaration, Whitespace, String, Whitespace, Name.Variable, Whitespace, String, Whitespace), 'action'),
|
|
(r'(symbol_map)(\s+)(\S+)(\s+)(.+?)$', bygroups(
|
|
Keyword.Declaration, Whitespace, String, Whitespace, Literal)),
|
|
(r'([a-zA-Z_0-9]+)(\s+)', bygroups(
|
|
Name.Variable, Whitespace), 'args'),
|
|
],
|
|
'action': [
|
|
(r'[a-z_0-9]+$', Name.Function, 'root'),
|
|
(r'[a-z_0-9]+', Name.Function, 'args'),
|
|
],
|
|
'mapargs': [
|
|
(r'.+$', mapargs, 'root'),
|
|
],
|
|
'args': [
|
|
(r'\s+', Whitespace, 'args'),
|
|
(r'\b(yes|no)\b$', Number.Bin, 'root'),
|
|
(r'\b(yes|no)\b', Number.Bin, 'args'),
|
|
(r'[+-]?[0-9]+\s*$', Number.Integer, 'root'),
|
|
(r'[+-]?[0-9.]+\s*$', Number.Float, 'root'),
|
|
(r'[+-]?[0-9]+', Number.Integer, 'args'),
|
|
(r'[+-]?[0-9.]+', Number.Float, 'args'),
|
|
(r'#[a-fA-F0-9]{3,6}\s*$', String, 'root'),
|
|
(r'#[a-fA-F0-9]{3,6}\s*', String, 'args'),
|
|
(r'.+', String, 'root'),
|
|
],
|
|
}
|
|
|
|
|
|
class SessionLexer(RegexLexer): # type: ignore
|
|
name = 'Session'
|
|
aliases = ['session']
|
|
filenames = ['*.session']
|
|
|
|
tokens = {
|
|
'root': [
|
|
(r'#.*?$', Comment.Single),
|
|
(r'[a-z][a-z0-9_]+', Name.Function, 'args'),
|
|
],
|
|
'args': [
|
|
(r'.*?$', Literal, 'root'),
|
|
]
|
|
}
|
|
|
|
|
|
def link_role(
|
|
name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []
|
|
) -> Tuple[List[nodes.reference], List[nodes.problematic]]:
|
|
text = text.replace('\n', ' ')
|
|
m = re.match(r'(.+)\s+<(.+?)>', text)
|
|
if m is None:
|
|
msg = inliner.reporter.error(f'link "{text}" not recognized', line=lineno)
|
|
prb = inliner.problematic(rawtext, rawtext, msg)
|
|
return [prb], [msg]
|
|
text, url = m.group(1, 2)
|
|
url = url.replace(' ', '')
|
|
set_classes(options)
|
|
node = nodes.reference(rawtext, text, refuri=url, **options)
|
|
return [node], []
|
|
|
|
|
|
opt_aliases: Dict[str, str] = {}
|
|
shortcut_slugs: Dict[str, Tuple[str, str]] = {}
|
|
|
|
|
|
def parse_opt_node(env: Any, sig: str, signode: Any) -> str:
|
|
"""Transform an option description into RST nodes."""
|
|
count = 0
|
|
firstname = ''
|
|
for potential_option in sig.split(', '):
|
|
optname = potential_option.strip()
|
|
if count:
|
|
signode += addnodes.desc_addname(', ', ', ')
|
|
text = optname.split('.', 1)[-1]
|
|
signode += addnodes.desc_name(text, text)
|
|
if not count:
|
|
firstname = optname
|
|
signode['allnames'] = [optname]
|
|
else:
|
|
signode['allnames'].append(optname)
|
|
opt_aliases[optname] = firstname
|
|
count += 1
|
|
if not firstname:
|
|
raise ValueError(f'{sig} is not a valid opt')
|
|
return firstname
|
|
|
|
|
|
def parse_shortcut_node(env: Any, sig: str, signode: Any) -> str:
|
|
"""Transform a shortcut description into RST nodes."""
|
|
conf_name, text = sig.split('.', 1)
|
|
signode += addnodes.desc_name(text, text)
|
|
return sig
|
|
|
|
|
|
def parse_action_node(env: Any, sig: str, signode: Any) -> str:
|
|
"""Transform an action description into RST nodes."""
|
|
signode += addnodes.desc_name(sig, sig)
|
|
return sig
|
|
|
|
|
|
def process_opt_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
|
|
conf_name, opt = target.partition('.')[::2]
|
|
if not opt:
|
|
conf_name, opt = 'kitty', conf_name
|
|
full_name = f'{conf_name}.{opt}'
|
|
return title, opt_aliases.get(full_name, full_name)
|
|
|
|
|
|
def process_action_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
|
|
return title, target
|
|
|
|
|
|
def process_shortcut_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
|
|
conf_name, slug = target.partition('.')[::2]
|
|
if not slug:
|
|
conf_name, slug = 'kitty', conf_name
|
|
full_name = f'{conf_name}.{slug}'
|
|
try:
|
|
target, stitle = shortcut_slugs[full_name]
|
|
except KeyError:
|
|
logger.warning(f'Unknown shortcut: {target}', location=refnode)
|
|
else:
|
|
if not has_explicit_title:
|
|
title = stitle
|
|
return title, target
|
|
|
|
|
|
def write_conf_docs(app: Any, all_kitten_names: Iterable[str]) -> None:
|
|
app.add_lexer('conf', ConfLexer() if version_info[0] < 3 else ConfLexer)
|
|
app.add_object_type(
|
|
'opt', 'opt',
|
|
indextemplate="pair: %s; Config Setting",
|
|
parse_node=parse_opt_node,
|
|
)
|
|
# Warn about opt references that could not be resolved
|
|
opt_role = app.registry.domain_roles['std']['opt']
|
|
opt_role.warn_dangling = True
|
|
opt_role.process_link = process_opt_link
|
|
|
|
app.add_object_type(
|
|
'shortcut', 'sc',
|
|
indextemplate="pair: %s; Keyboard Shortcut",
|
|
parse_node=parse_shortcut_node,
|
|
)
|
|
sc_role = app.registry.domain_roles['std']['sc']
|
|
sc_role.warn_dangling = True
|
|
sc_role.process_link = process_shortcut_link
|
|
shortcut_slugs.clear()
|
|
|
|
app.add_object_type(
|
|
'action', 'ac',
|
|
indextemplate="pair: %s; Action",
|
|
parse_node=parse_action_node,
|
|
)
|
|
ac_role = app.registry.domain_roles['std']['ac']
|
|
ac_role.warn_dangling = True
|
|
ac_role.process_link = process_action_link
|
|
|
|
def generate_default_config(definition: Definition, name: str) -> None:
|
|
with open(f'generated/conf-{name}.rst', 'w', encoding='utf-8') as f:
|
|
print('.. highlight:: conf\n', file=f)
|
|
f.write('\n'.join(definition.as_rst(name, shortcut_slugs)))
|
|
|
|
conf_name = re.sub(r'^kitten-', '', name) + '.conf'
|
|
with open(f'generated/conf/{conf_name}', 'w', encoding='utf-8') as f:
|
|
text = '\n'.join(definition.as_conf(commented=True))
|
|
print(text, file=f)
|
|
|
|
from kitty.options.definition import definition
|
|
generate_default_config(definition, 'kitty')
|
|
|
|
from kittens.runner import get_kitten_conf_docs
|
|
for kitten in all_kitten_names:
|
|
defn = get_kitten_conf_docs(kitten)
|
|
if defn is not None:
|
|
generate_default_config(defn, f'kitten-{kitten}')
|
|
|
|
from kitty.actions import as_rst
|
|
with open('generated/actions.rst', 'w', encoding='utf-8') as f:
|
|
f.write(as_rst())
|
|
|
|
from kitty.rc.base import MATCH_TAB_OPTION, MATCH_WINDOW_OPTION
|
|
with open('generated/matching.rst', 'w') as f:
|
|
print('Matching windows', file=f)
|
|
print('______________________________', file=f)
|
|
w = 'm' + MATCH_WINDOW_OPTION[MATCH_WINDOW_OPTION.find('Match') + 1:]
|
|
print('When matching windows,', w, file=f)
|
|
print('Matching tabs', file=f)
|
|
print('______________________________', file=f)
|
|
w = 'm' + MATCH_TAB_OPTION[MATCH_TAB_OPTION.find('Match') + 1:]
|
|
print('When matching tabs,', w, file=f)
|
|
|
|
# }}}
|
|
|
|
|
|
def add_html_context(app: Any, pagename: str, templatename: str, context: Any, doctree: Any, *args: Any) -> None:
|
|
context['analytics_id'] = app.config.analytics_id
|
|
if 'toctree' in context:
|
|
# this is needed with furo to use all titles from pages
|
|
# in the sidebar (global) toc
|
|
original_toctee_function = context['toctree']
|
|
|
|
def include_sub_headings(**kwargs: Any) -> Any:
|
|
kwargs['titles_only'] = False
|
|
return original_toctee_function(**kwargs)
|
|
|
|
context['toctree'] = include_sub_headings
|
|
|
|
|
|
@lru_cache
|
|
def monkeypatch_man_writer() -> None:
|
|
'''
|
|
Monkeypatch the docutils man translator to be nicer
|
|
'''
|
|
from docutils.nodes import Element
|
|
from docutils.writers.manpage import Table, Translator
|
|
from sphinx.writers.manpage import ManualPageTranslator
|
|
|
|
# Generate nicer tables https://sourceforge.net/p/docutils/bugs/475/
|
|
class PatchedTable(Table): # type: ignore
|
|
_options: list[str]
|
|
def __init__(self) -> None:
|
|
super().__init__()
|
|
self.needs_border_removal = self._options == ['center']
|
|
if self.needs_border_removal:
|
|
self._options = ['box', 'center']
|
|
|
|
def as_list(self) -> list[str]:
|
|
ans: list[str] = super().as_list()
|
|
if self.needs_border_removal:
|
|
# remove side and top borders as we use box in self._options
|
|
ans[2] = ans[2][1:]
|
|
a, b = ans[2].rpartition('|')[::2]
|
|
ans[2] = a + b
|
|
if ans[3] == '_\n':
|
|
del ans[3] # top border
|
|
del ans[-2] # bottom border
|
|
return ans
|
|
def visit_table(self: ManualPageTranslator, node: object) -> None:
|
|
setattr(self, '_active_table', PatchedTable())
|
|
setattr(ManualPageTranslator, 'visit_table', visit_table)
|
|
|
|
# Improve header generation
|
|
def header(self: ManualPageTranslator) -> str:
|
|
di = getattr(self, '_docinfo')
|
|
di['ktitle'] = di['title'].replace('_', '-')
|
|
th = (".TH \"%(ktitle)s\" %(manual_section)s"
|
|
" \"%(date)s\" \"%(version)s\"") % di
|
|
if di["manual_group"]:
|
|
th += " \"%(manual_group)s\"" % di
|
|
th += "\n"
|
|
sh_tmpl: str = (".SH Name\n"
|
|
"%(ktitle)s \\- %(subtitle)s\n")
|
|
return th + sh_tmpl % di # type: ignore
|
|
|
|
setattr(ManualPageTranslator, 'header', header)
|
|
|
|
def visit_image(self: ManualPageTranslator, node: Element) -> None:
|
|
pass
|
|
|
|
def depart_image(self: ManualPageTranslator, node: Element) -> None:
|
|
pass
|
|
|
|
def depart_figure(self: ManualPageTranslator, node: Element) -> None:
|
|
self.body.append(' (images not supported)\n')
|
|
Translator.depart_figure(self, node)
|
|
|
|
setattr(ManualPageTranslator, 'visit_image', visit_image)
|
|
setattr(ManualPageTranslator, 'depart_image', depart_image)
|
|
setattr(ManualPageTranslator, 'depart_figure', depart_figure)
|
|
|
|
orig_astext = Translator.astext
|
|
def astext(self: Translator) -> Any:
|
|
b = []
|
|
for line in self.body:
|
|
if line.startswith('.SH'):
|
|
x, y = line.split(' ', 1)
|
|
parts = y.splitlines(keepends=True)
|
|
parts[0] = parts[0].capitalize()
|
|
line = x + ' ' + '\n'.join(parts)
|
|
b.append(line)
|
|
self.body = b
|
|
return orig_astext(self)
|
|
setattr(Translator, 'astext', astext)
|
|
|
|
|
|
def setup_man_pages() -> None:
|
|
from kittens.runner import get_kitten_cli_docs
|
|
base = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
|
for x in glob.glob(os.path.join(base, 'docs/kittens/*.rst')):
|
|
kn = os.path.basename(x).rpartition('.')[0]
|
|
if kn == 'custom':
|
|
continue
|
|
cd = get_kitten_cli_docs(kn) or {}
|
|
khn = kn.replace('_', '-')
|
|
man_pages.append((f'kittens/{kn}', 'kitten-' + khn, cd.get('short_desc', 'kitten Documentation'), [author], 1))
|
|
monkeypatch_man_writer()
|
|
|
|
|
|
def build_extra_man_pages() -> None:
|
|
base = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
|
kitten = os.environ.get('KITTEN_EXE_FOR_DOCS', os.path.join(base, 'kitty/launcher/kitten'))
|
|
if not os.path.exists(kitten):
|
|
kitten = os.path.join(base, 'kitty/launcher/kitty.app/Contents/MacOS/kitten')
|
|
if not os.path.exists(kitten):
|
|
subprocess.call(['find', os.path.join(base, 'kitty/launcher')])
|
|
raise Exception(f'The kitten binary {kitten} is not built cannot generate man pages')
|
|
raw = subprocess.check_output([kitten, '-h']).decode()
|
|
started = 0
|
|
names = set()
|
|
for line in raw.splitlines():
|
|
if line.strip() == '@':
|
|
started = len(line.rstrip()[:-1])
|
|
q = line.strip()
|
|
if started and len(q.split()) == 1 and not q.startswith('-') and ':' not in q:
|
|
if len(line) - len(line.lstrip()) == started:
|
|
if not os.path.exists(os.path.join(base, f'docs/kittens/{q}.rst')):
|
|
names.add(q)
|
|
cwd = os.path.join(base, 'docs/_build/man')
|
|
subprocess.check_call([kitten, '__generate_man_pages__'], cwd=cwd)
|
|
subprocess.check_call([kitten, '__generate_man_pages__'] + list(names), cwd=cwd)
|
|
|
|
|
|
if building_man_pages:
|
|
setup_man_pages()
|
|
|
|
|
|
def build_finished(*a: Any, **kw: Any) -> None:
|
|
if building_man_pages:
|
|
build_extra_man_pages()
|
|
|
|
|
|
def setup(app: Any) -> None:
|
|
os.makedirs('generated/conf', exist_ok=True)
|
|
from kittens.runner import all_kitten_names
|
|
kn = all_kitten_names()
|
|
write_cli_docs(kn)
|
|
write_remote_control_protocol_docs()
|
|
write_conf_docs(app, kn)
|
|
app.add_config_value('string_replacements', {}, True)
|
|
app.connect('source-read', replace_string)
|
|
app.add_config_value('analytics_id', '', 'env')
|
|
app.connect('html-page-context', add_html_context)
|
|
app.connect('build-finished', build_finished)
|
|
app.add_lexer('session', SessionLexer() if version_info[0] < 3 else SessionLexer)
|
|
app.add_role('link', link_role)
|
|
app.add_role('commit', commit_role)
|