Fix more documentation wibbles
[ghc.git] / docs / users_guide / conf.py
1 # -*- coding: utf-8 -*-
2 #
3 # GHC User's Guide documentation build configuration file
4 #
5 # This file is execfile()d with the current directory set to its
6 # containing dir.
7 #
8 import sys
9 import os
10
11 # Support for :base-ref:, etc.
12 sys.path.insert(0, os.path.abspath('.'))
13 from ghc_config import extlinks, version
14
15 extensions = ['sphinx.ext.extlinks', 'sphinx.ext.mathjax']
16
17 templates_path = ['.templates']
18 source_suffix = '.rst'
19 source_encoding = 'utf-8-sig'
20 master_doc = 'index'
21
22 # General information about the project.
23 project = u'Glasgow Haskell Compiler'
24 copyright = u'2015, GHC Team'
25 # N.B. version comes from ghc_config
26 release = version # The full version, including alpha/beta/rc tags.
27
28 # Syntax highlighting
29 highlight_language = 'haskell'
30 pygments_style = 'tango'
31
32 # List of patterns, relative to source directory, that match files and
33 # directories to ignore when looking for source files.
34 exclude_patterns = ['.build', "*.gen.rst"]
35
36 # -- Options for HTML output ---------------------------------------------
37
38 # The name for this set of Sphinx documents. If None, it defaults to
39 # "<project> v<release> documentation".
40 html_title = "Glasgow Haskell Compiler %s User's Guide" % release
41 html_short_title = "GHC %s User's Guide" % release
42 html_theme_path = ['.']
43 html_theme = 'ghc-theme'
44 html_logo = None
45 html_static_path = ['images']
46 # Convert quotes and dashes to typographically correct entities
47 html_use_smartypants = True
48 html_use_opensearch = 'https://downloads.haskell.org/~ghc/master/users-guide'
49 html_show_copyright = True
50
51 # If true, an OpenSearch description file will be output, and all pages will
52 # contain a <link> tag referring to it. The value of this option must be the
53 # base URL from which the finished HTML is served.
54 #html_use_opensearch = ''
55
56 # This is the file name suffix for HTML files (e.g. ".xhtml").
57 #html_file_suffix = None
58
59 # Output file base name for HTML help builder.
60 htmlhelp_basename = 'GHCUsersGuide'
61
62
63 # -- Options for LaTeX output ---------------------------------------------
64
65 latex_elements = {
66 'inputenc': '',
67 'utf8extra': '',
68 'preamble': '''
69 \usepackage{fontspec}
70 \usepackage{makeidx}
71 \setsansfont{DejaVu Sans}
72 \setromanfont{DejaVu Serif}
73 \setmonofont{DejaVu Sans Mono}
74 ''',
75 }
76
77 # Grouping the document tree into LaTeX files. List of tuples
78 # (source start file, target name, title,
79 # author, documentclass [howto, manual, or own class]).
80 latex_documents = [
81 ('index', 'users_guide.tex', u'GHC User\'s Guide Documentation',
82 u'GHC Team', 'manual'),
83 ]
84
85 # The name of an image file (relative to this directory) to place at the top of
86 # the title page.
87 latex_logo = 'images/logo.pdf'
88
89 # If true, show page references after internal links.
90 latex_show_pagerefs = True
91
92
93 # -- Options for manual page output ---------------------------------------
94
95 # One entry per manual page. List of tuples
96 # (source start file, name, description, authors, manual section).
97 man_pages = [
98 ('ghc', 'ghc', 'the Glasgow Haskell Compiler', 'The GHC Team', 1)
99 ]
100
101 # If true, show URL addresses after external links.
102 #man_show_urls = False
103
104
105 # -- Options for Texinfo output -------------------------------------------
106
107 # Grouping the document tree into Texinfo files. List of tuples
108 # (source start file, target name, title, author,
109 # dir menu entry, description, category)
110 texinfo_documents = [
111 ('index', 'GHCUsersGuide', u'GHC User\'s Guide',
112 u'GHC Team', 'GHCUsersGuide', 'The Glasgow Haskell Compiler.',
113 'Compilers'),
114 ]
115
116 from sphinx import addnodes
117 from docutils import nodes
118
119 # The following functions parse flag declarations, and then have two jobs. First
120 # they modify the docutils node `signode` for the proper display of the
121 # declaration. Second, they return the name used to reference the flag.
122 # (i.e. return "name" implies you reference the flag with :flag:`name`)
123 def parse_ghci_cmd(env, sig, signode):
124 parts = sig.split(';')
125 name = parts[0]
126 args = ''
127 if len(parts) > 1:
128 args = parts[1]
129 # Bold name
130 signode += addnodes.desc_name(name, name)
131 # Smaller args
132 signode += addnodes.desc_addname(args, args)
133 # Reference name
134 return name
135
136 def parse_flag(env, sig, signode):
137
138 # Break flag into name and args
139 import re
140 parts = re.split('( |=|\\[)', sig, 1)
141 flag = parts[0]
142 args = ''
143 if len(parts) > 1:
144 args = ''.join(parts[1:])
145
146 # Bold printed name
147 signode += addnodes.desc_name(flag, flag)
148 # Smaller arguments
149 signode += addnodes.desc_addname(args, args)
150 # Reference name left unchanged
151 return sig
152
153 def setup(app):
154 from sphinx.util.docfields import Field, TypedField
155
156 increase_python_stack()
157
158 # the :ghci-cmd: directive used in ghci.rst
159 app.add_object_type('ghci-cmd', 'ghci-cmd',
160 parse_node=parse_ghci_cmd,
161 objname='GHCi command',
162 indextemplate='pair: %s; GHCi command')
163
164 app.add_object_type('ghc-flag', 'ghc-flag',
165 objname='GHC command-line option',
166 parse_node=parse_flag,
167 indextemplate='pair: %s; GHC option',
168 doc_field_types=[
169 Field('since', label='Introduced in GHC version', names=['since']),
170 Field('default', label='Default value', names=['default']),
171 Field('static')
172 ])
173
174 app.add_object_type('rts-flag', 'rts-flag',
175 objname='runtime system command-line option',
176 parse_node=parse_flag,
177 indextemplate='pair: %s; RTS option',
178 doc_field_types=[
179 Field('since', label='Introduced in GHC version', names=['since']),
180 ])
181
182 def increase_python_stack():
183 # Workaround sphinx-build recursion limit overflow:
184 # pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
185 # RuntimeError: maximum recursion depth exceeded while pickling an object
186 #
187 # Default python allows recursion depth of 1000 calls.
188 sys.setrecursionlimit(10000)