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