fork/fish-shell
git clone https://git.julia.blue/fork/fish-shell
f0054336e
master
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 : 19import sphinx_markdown_builder 20 21extensions = [ 22"sphinx_markdown_builder" , 23 ] 24except ImportError : 25pass 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 ): 33options = options or {} 34try : 35issue_num = int (text .strip ()) 36if issue_num <= 0 : 37raise ValueError 38except ValueError : 39msg = inliner .reporter .error ('Invalid issue number: "%s"' % text ,line = lineno ) 40prb = inliner .problematic (rawtext ,rawtext ,msg ) 41return [prb ], [msg ] 42template = issue_url + "/{n}" 43ref = template .format (n = issue_num ) 44issue_text = "#{issue_no}" .format (issue_no = issue_num ) 45link = nodes .reference (text = issue_text ,refuri = ref ,** options ) 46return [link ], [] 47 48 49def extract_sections (app ,env ): 50if app .builder .name != "man" : 51return 52output_file = app .config .fish_help_sections_output 53if output_file == "" : 54return 55 56import re 57 58sections = [] 59for docname ,info in env .tocs .items (): 60for node in info .traverse (): 61if not isinstance (node ,nodes .reference ): 62continue 63anchor = node ["anchorname" ] 64if re .match (r"^#id\d+$" ,anchor ): 65continue 66if anchor and docname .startswith ("cmds/" ): 67continue 68if anchor and docname == "relnotes" : 69continue 70sections .append (docname + anchor ) 71sections .sort () 72for section in sections : 73assert re .match (r"[\w-]" ,section ), ( 74f"Unsupported characters in section path: { section } " 75 ) 76help_sections = "" .join (f" { section } \n" for section in sections ) 77Path (output_file ).write_text (help_sections ) 78 79 80def remove_fish_indent_lexer (app ): 81if app .builder .name in ("man" ,"markdown" ): 82del lexers ["fish-docs-samples" ] 83 84 85# -- Load our extensions ------------------------------------------------- 86def setup (app ): 87# Our own pygments lexers 88this_dir = os .path .dirname (os .path .realpath (__file__ )) 89sys .path .insert (0 ,this_dir ) 90from fish_indent_lexer import FishIndentLexer 91from fish_synopsis import FishSynopsisDirective ,FishSynopsisLexer 92 93lexers ["fish-docs-samples" ]= FishIndentLexer () 94lexers ["fish-synopsis" ]= FishSynopsisLexer () 95app .add_directive ("synopsis" ,FishSynopsisDirective ) 96 97app .add_config_value ("issue_url" ,default = None ,rebuild = "html" ) 98app .add_config_value ( 99"fish_help_sections_output" , 100default = "" , 101rebuild = "man" , 102types = str , 103 ) 104app .add_role ("issue" ,issue_role ) 105 106app .connect ("builder-inited" ,remove_fish_indent_lexer ) 107app .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 ( 204master_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""" 221with open (path ,encoding = "utf8" )as opened : 222for line in opened : 223if line .startswith (name + " - " ): 224_ ,desc = line .split (" - " ,1 ) 225return desc .strip () 226elif line .startswith ("``" + name + "`` - " ): 227_ ,desc = line .split ("`` - " ,1 ) 228return desc .strip ("`" ) 229raise 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 ], 2541 , 255 ), 256 ("faq" ,"fish-faq" ,"" , [author ],1 ), 257] 258for path in sorted (set (glob ("cmds/*.rst" ))- set (glob (fish_exclude_patterns ))): 259docname = os .path .splitext (path )[0 ] 260cmd = os .path .basename (docname ) 261man_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 ( 271master_doc , 272"fish-shell" , 273"fish-shell Documentation" , 274author , 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+" ]