users_guide: Convert mkUserGuidePart generation to a Sphinx extension
[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', 'flags']
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']
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 \setlength{\\tymin}{45pt}
76 ''',
77 }
78
79 # Grouping the document tree into LaTeX files. List of tuples
80 # (source start file, target name, title,
81 # author, documentclass [howto, manual, or own class]).
82 latex_documents = [
83 ('index', 'users_guide.tex', u'GHC User\'s Guide Documentation',
84 u'GHC Team', 'manual'),
85 ]
86
87 # The name of an image file (relative to this directory) to place at the top of
88 # the title page.
89 latex_logo = 'images/logo.pdf'
90
91 # If true, show page references after internal links.
92 latex_show_pagerefs = True
93
94
95 # -- Options for manual page output ---------------------------------------
96
97 # One entry per manual page. List of tuples
98 # (source start file, name, description, authors, manual section).
99 man_pages = [
100 ('ghc', 'ghc', 'the Glasgow Haskell Compiler', 'The GHC Team', 1)
101 ]
102
103 # If true, show URL addresses after external links.
104 #man_show_urls = False
105
106
107 # -- Options for Texinfo output -------------------------------------------
108
109 # Grouping the document tree into Texinfo files. List of tuples
110 # (source start file, target name, title, author,
111 # dir menu entry, description, category)
112 texinfo_documents = [
113 ('index', 'GHCUsersGuide', u'GHC User\'s Guide',
114 u'GHC Team', 'GHCUsersGuide', 'The Glasgow Haskell Compiler.',
115 'Compilers'),
116 ]
117
118 from sphinx import addnodes
119 from docutils import nodes
120
121 # The following functions parse flag declarations, and then have two jobs. First
122 # they modify the docutils node `signode` for the proper display of the
123 # declaration. Second, they return the name used to reference the flag.
124 # (i.e. return "name" implies you reference the flag with :flag:`name`)
125 def parse_ghci_cmd(env, sig, signode):
126 parts = sig.split(';')
127 name = parts[0]
128 args = ''
129 if len(parts) > 1:
130 args = parts[1]
131 # Bold name
132 signode += addnodes.desc_name(name, name)
133 # Smaller args
134 signode += addnodes.desc_addname(args, args)
135 # Reference name
136 return name
137
138 def parse_flag(env, sig, signode):
139
140 # Break flag into name and args
141 import re
142 parts = re.split('( |=|\\[)', sig, 1)
143 flag = parts[0]
144 args = ''
145 if len(parts) > 1:
146 args = ''.join(parts[1:])
147
148 # Bold printed name
149 signode += addnodes.desc_name(flag, flag)
150 # Smaller arguments
151 signode += addnodes.desc_addname(args, args)
152 # Reference name left unchanged
153 return sig
154
155 def haddock_role(lib):
156 """
157 For instance,
158 * reference to module: :base-ref:`Control.Applicative.`
159 * reference to identifier: :base-ref:`Control.Applicative.pure`
160 * reference to type: :base-ref:`Control.Applicative.Applicative`
161 """
162 path = '%s/%s-%s' % (ghc_config.libs_base_uri, lib, ghc_config.lib_versions[lib])
163 def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
164 try:
165 parts = text.split('.')
166 module_parts = parts[:-1]
167 thing = parts[-1]
168 if thing != '':
169 # reference to type or identifier
170 tag = 't' if thing[0].isupper() else 'v'
171 anchor = '#%s:%s' % (tag, thing)
172 link_text = text
173 else:
174 # reference to module
175 anchor = ''
176 link_text = '.'.join(module_parts)
177
178 uri = '%s/%s.html%s' % (path, '-'.join(module_parts), anchor)
179 node = nodes.reference(link_text, link_text, refuri=uri)
180 return [node], []
181 except ValueError:
182 msg = inliner.reporter.error('')
183
184 return role
185
186 def setup(app):
187 from sphinx.util.docfields import Field, TypedField
188
189 increase_python_stack()
190
191 # the :ghci-cmd: directive used in ghci.rst
192 app.add_object_type('ghci-cmd', 'ghci-cmd',
193 parse_node=parse_ghci_cmd,
194 objname='GHCi command',
195 indextemplate='pair: %s; GHCi command')
196
197 # Haddock references
198 app.add_role('th-ref', haddock_role('template-haskell'))
199 app.add_role('base-ref', haddock_role('base'))
200 app.add_role('cabal-ref', haddock_role('Cabal'))
201 app.add_role('ghc-compact-ref', haddock_role('ghc-compact'))
202 app.add_role('ghc-prim-ref', haddock_role('ghc-prim'))
203 app.add_role('parallel-ref', haddock_role('parallel'))
204 app.add_role('array-ref', haddock_role('array'))
205
206 app.add_object_type('rts-flag', 'rts-flag',
207 objname='runtime system command-line option',
208 parse_node=parse_flag,
209 indextemplate='pair: %s; RTS option',
210 doc_field_types=[
211 Field('since', label='Introduced in GHC version', names=['since']),
212 ])
213
214 def increase_python_stack():
215 # Workaround sphinx-build recursion limit overflow:
216 # pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
217 # RuntimeError: maximum recursion depth exceeded while pickling an object
218 #
219 # Default python allows recursion depth of 1000 calls.
220 sys.setrecursionlimit(10000)