##// END OF EJS Templates
Corrected a typo in the format string for strftime
Brad Reisfeld -
Show More
@@ -1,261 +1,261 b''
1 1 """Module that allows custom Sphinx parameters to be set on the notebook and
2 2 on the 'other' object passed into Jinja. Called prior to Jinja conversion
3 3 process.
4 4 """
5 5 #-----------------------------------------------------------------------------
6 6 # Copyright (c) 2013, the IPython Development Team.
7 7 #
8 8 # Distributed under the terms of the Modified BSD License.
9 9 #
10 10 # The full license is in the file COPYING.txt, distributed with this software.
11 11 #-----------------------------------------------------------------------------
12 12
13 13 #-----------------------------------------------------------------------------
14 14 # Imports
15 15 #-----------------------------------------------------------------------------
16 16
17 17 from __future__ import print_function, absolute_import
18 18
19 19 # Stdlib imports
20 20 # Used to find Sphinx package location
21 21 import sphinx
22 22 import os.path
23 23
24 24 # Used to set the default date to today's date
25 25 from datetime import date
26 26
27 27 # Third-party imports
28 28 # Needed for Pygments latex definitions.
29 29 from pygments.formatters import LatexFormatter
30 30
31 31 # Our own imports
32 32 # Configurable traitlets
33 33 from IPython.utils.traitlets import Unicode, Bool
34 34
35 35 # Needed to override transformer
36 36 from .activatable import (ActivatableTransformer) #TODO
37 37
38 38 from IPython.nbconvert.utils import console
39 39
40 40 #-----------------------------------------------------------------------------
41 41 # Classes and functions
42 42 #-----------------------------------------------------------------------------
43 43
44 44 class SphinxTransformer(ActivatableTransformer):
45 45 """
46 46 Sphinx utility transformer.
47 47
48 48 This transformer is used to set variables needed by the latex to build
49 49 Sphinx stylized templates.
50 50 """
51 51
52 52 interactive = Bool(False, config=True, help="""
53 53 Allows you to define whether or not the Sphinx exporter will prompt
54 54 you for input during the conversion process. If this is set to false,
55 55 the author, version, release, date, and chapter_style traits should
56 56 be set.
57 57 """)
58 58
59 59 author = Unicode("Unknown Author", config=True, help="Author name")
60 60
61 61 version = Unicode("", config=True, help="""
62 62 Version number
63 63 You can leave this blank if you do not want to render a version number.
64 64 Example: "1.0.0"
65 65 """)
66 66
67 67 release = Unicode("", config=True, help="""
68 68 Release name
69 69 You can leave this blank if you do not want to render a release name.
70 70 Example: "Rough Draft"
71 71 """)
72 72
73 73 publish_date = Unicode("", config=True, help="""
74 74 Publish date
75 75 This is the date to render on the document as the publish date.
76 76 Leave this blank to default to todays date.
77 77 Example: "June 12, 1990"
78 78 """)
79 79
80 80 chapter_style = Unicode("Bjarne", config=True, help="""
81 81 Sphinx chapter style
82 82 This is the style to use for the chapter headers in the document.
83 83 You may choose one of the following:
84 84 "Bjarne" (default)
85 85 "Lenny"
86 86 "Glenn"
87 87 "Conny"
88 88 "Rejne"
89 89 "Sonny" (used for international documents)
90 90 """)
91 91
92 92 output_style = Unicode("notebook", config=True, help="""
93 93 Nbconvert Ipython
94 94 notebook input/output formatting style.
95 95 You may choose one of the following:
96 96 "simple (recommended for long code segments)"
97 97 "notebook" (default)
98 98 """)
99 99
100 100 center_output = Bool(False, config=True, help="""
101 101 Optional attempt to center all output. If this is false, no additional
102 102 formatting is applied.
103 103 """)
104 104
105 105 use_headers = Bool(True, config=True, help="""
106 106 Whether not a header should be added to the document.
107 107 """)
108 108
109 109 #Allow the user to override the title of the notebook (useful for
110 110 #fancy document titles that the file system doesn't support.)
111 111 overridetitle = Unicode("", config=True, help="")
112 112
113 113
114 114 def call(self, nb, resources):
115 115 """
116 116 Sphinx transformation to apply on each notebook.
117 117
118 118 Parameters
119 119 ----------
120 120 nb : NotebookNode
121 121 Notebook being converted
122 122 resources : dictionary
123 123 Additional resources used in the conversion process. Allows
124 124 transformers to pass variables into the Jinja engine.
125 125 """
126 126
127 127 # TODO: Add versatile method of additional notebook metadata. Include
128 128 # handling of multiple files. For now use a temporay namespace,
129 129 # '_draft' to signify that this needs to change.
130 130 if not "_draft" in nb.metadata:
131 131 nb.metadata._draft = {}
132 132
133 133 if not "sphinx" in resources:
134 134 resources["sphinx"] = {}
135 135
136 136 if self.interactive:
137 137
138 138 # Prompt the user for additional meta data that doesn't exist currently
139 139 # but would be usefull for Sphinx.
140 140 nb.metadata._draft["author"] = self._prompt_author()
141 141 nb.metadata._draft["version"] = self._prompt_version()
142 142 nb.metadata._draft["release"] = self._prompt_release()
143 143 nb.metadata._draft["date"] = self._prompt_date()
144 144
145 145 # Prompt the user for the document style.
146 146 resources["sphinx"]["chapterstyle"] = self._prompt_chapter_title_style()
147 147 resources["sphinx"]["outputstyle"] = self._prompt_output_style()
148 148
149 149 # Small options
150 150 resources["sphinx"]["centeroutput"] = console.prompt_boolean("Do you want to center the output? (false)", False)
151 151 resources["sphinx"]["header"] = console.prompt_boolean("Should a Sphinx document header be used? (true)", True)
152 152 else:
153 153
154 154 # Try to use the traitlets.
155 155 nb.metadata._draft["author"] = self.author
156 156 nb.metadata._draft["version"] = self.version
157 157 nb.metadata._draft["release"] = self.release
158 158
159 159 # Use todays date if none is provided.
160 160 if len(self.publish_date.strip()) == 0:
161 nb.metadata._draft["date"] = date.today().strftime("%B %-d, %Y")
161 nb.metadata._draft["date"] = date.today().strftime("%B %d, %Y")
162 162 else:
163 163 nb.metadata._draft["date"] = self.publish_date
164 164
165 165 # Sphinx traitlets.
166 166 resources["sphinx"]["chapterstyle"] = self.chapter_style
167 167 resources["sphinx"]["outputstyle"] = self.output_style
168 168 resources["sphinx"]["centeroutput"] = self.center_output
169 169 resources["sphinx"]["header"] = self.use_headers
170 170
171 171 # Find and pass in the path to the Sphinx dependencies.
172 172 resources["sphinx"]["texinputs"] = os.path.realpath(os.path.join(sphinx.__file__, "..", "texinputs"))
173 173
174 174 # Generate Pygments definitions for Latex
175 175 resources["sphinx"]["pygment_definitions"] = self._generate_pygments_latex_def()
176 176
177 177 if not (self.overridetitle == None or len(self.overridetitle.strip()) == 0):
178 178 nb.metadata.name = self.overridetitle
179 179
180 180 # End
181 181 return nb, resources
182 182
183 183
184 184 def _generate_pygments_latex_def(self):
185 185 """
186 186 Generate the pygments latex definitions that allows pygments
187 187 to work in latex.
188 188 """
189 189
190 190 return LatexFormatter().get_style_defs()
191 191
192 192
193 193 def _prompt_author(self):
194 194 """
195 195 Prompt the user to input an Author name
196 196 """
197 197 return console.input("Author name: ")
198 198
199 199
200 200 def _prompt_version(self):
201 201 """
202 202 prompt the user to enter a version number
203 203 """
204 204 return console.input("Version (ie ""1.0.0""): ")
205 205
206 206
207 207 def _prompt_release(self):
208 208 """
209 209 Prompt the user to input a release name
210 210 """
211 211
212 212 return console.input("Release Name (ie ""Rough draft""): ")
213 213
214 214
215 215 def _prompt_date(self):
216 216 """
217 217 Prompt the user to enter a date
218 218 """
219 219
220 default_date = date.today().strftime("%B %-d, %Y")
220 default_date = date.today().strftime("%B %d, %Y")
221 221 user_date = console.input("Date (deafults to \"" + default_date + "\"): ")
222 222 if len(user_date.strip()) == 0:
223 223 user_date = default_date
224 224 return user_date
225 225
226 226
227 227 def _prompt_output_style(self):
228 228 """
229 229 Prompts the user to pick an IPython output style.
230 230 """
231 231
232 232 # Dictionary of available output styles
233 233 styles = {1: "simple",
234 234 2: "notebook"}
235 235
236 236 #Append comments to the menu when displaying it to the user.
237 237 comments = {1: "(recommended for long code segments)",
238 238 2: "(default)"}
239 239
240 240 return console.prompt_dictionary(styles, default_style=2, menu_comments=comments)
241 241
242 242
243 243 def _prompt_chapter_title_style(self):
244 244 """
245 245 Prompts the user to pick a Sphinx chapter style
246 246 """
247 247
248 248 # Dictionary of available Sphinx styles
249 249 styles = {1: "Bjarne",
250 250 2: "Lenny",
251 251 3: "Glenn",
252 252 4: "Conny",
253 253 5: "Rejne",
254 254 6: "Sonny"}
255 255
256 256 #Append comments to the menu when displaying it to the user.
257 257 comments = {1: "(default)",
258 258 6: "(for international documents)"}
259 259
260 260 return console.prompt_dictionary(styles, menu_comments=comments)
261 261
General Comments 0
You need to be logged in to leave comments. Login now