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