Merge lp:~renamer-developers/renamer/documentation into lp:renamer
- documentation
- Merge into trunk
Proposed by
Jonathan Jacobs
Status: | Merged | ||||
---|---|---|---|---|---|
Approved by: | Tristan Seligmann | ||||
Approved revision: | 133 | ||||
Merged at revision: | 88 | ||||
Proposed branch: | lp:~renamer-developers/renamer/documentation | ||||
Merge into: | lp:renamer | ||||
Diff against target: |
1095 lines (+942/-94) 10 files modified
.bzrignore (+1/-0) docs/Makefile (+130/-0) docs/code/plugins_command.py (+42/-0) docs/conf.py (+216/-0) docs/index.rst (+16/-0) docs/make.bat (+155/-0) docs/manual.rst (+247/-0) docs/plugins.rst (+134/-0) docs/rn.1 (+0/-93) renamer/plugins/undo.py (+1/-1) |
||||
To merge this branch: | bzr merge lp:~renamer-developers/renamer/documentation | ||||
Related bugs: |
|
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Tristan Seligmann | Approve | ||
Review via email: mp+39450@code.launchpad.net |
Commit message
Description of the change
Move to using Sphinx for documentation purposes. HTML versions of the documentation are conveniently available for proofreading at <http://
To post a comment you must log in.
- 132. By Jonathan Jacobs
-
Merge trunk.
Revision history for this message
Jonathan Jacobs (jjacobs) wrote : | # |
- 133. By Jonathan Jacobs
-
Merge trunk.
Revision history for this message
Tristan Seligmann (mithrandi) : | # |
review:
Approve
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | === modified file '.bzrignore' |
2 | --- .bzrignore 2009-05-07 10:45:13 +0000 |
3 | +++ .bzrignore 2010-11-01 08:51:04 +0000 |
4 | @@ -1,1 +1,2 @@ |
5 | dropin.cache |
6 | +_build |
7 | |
8 | === added file 'docs/Makefile' |
9 | --- docs/Makefile 1970-01-01 00:00:00 +0000 |
10 | +++ docs/Makefile 2010-11-01 08:51:04 +0000 |
11 | @@ -0,0 +1,130 @@ |
12 | +# Makefile for Sphinx documentation |
13 | +# |
14 | + |
15 | +# You can set these variables from the command line. |
16 | +SPHINXOPTS = |
17 | +SPHINXBUILD = sphinx-build |
18 | +PAPER = a4 |
19 | +BUILDDIR = _build |
20 | + |
21 | +# Internal variables. |
22 | +PAPEROPT_a4 = -D latex_paper_size=a4 |
23 | +PAPEROPT_letter = -D latex_paper_size=letter |
24 | +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . |
25 | + |
26 | +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest |
27 | + |
28 | +help: |
29 | + @echo "Please use \`make <target>' where <target> is one of" |
30 | + @echo " html to make standalone HTML files" |
31 | + @echo " dirhtml to make HTML files named index.html in directories" |
32 | + @echo " singlehtml to make a single large HTML file" |
33 | + @echo " pickle to make pickle files" |
34 | + @echo " json to make JSON files" |
35 | + @echo " htmlhelp to make HTML files and a HTML help project" |
36 | + @echo " qthelp to make HTML files and a qthelp project" |
37 | + @echo " devhelp to make HTML files and a Devhelp project" |
38 | + @echo " epub to make an epub" |
39 | + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" |
40 | + @echo " latexpdf to make LaTeX files and run them through pdflatex" |
41 | + @echo " text to make text files" |
42 | + @echo " man to make manual pages" |
43 | + @echo " changes to make an overview of all changed/added/deprecated items" |
44 | + @echo " linkcheck to check all external links for integrity" |
45 | + @echo " doctest to run all doctests embedded in the documentation (if enabled)" |
46 | + |
47 | +clean: |
48 | + -rm -rf $(BUILDDIR)/* |
49 | + |
50 | +html: |
51 | + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html |
52 | + @echo |
53 | + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." |
54 | + |
55 | +dirhtml: |
56 | + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml |
57 | + @echo |
58 | + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." |
59 | + |
60 | +singlehtml: |
61 | + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml |
62 | + @echo |
63 | + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." |
64 | + |
65 | +pickle: |
66 | + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle |
67 | + @echo |
68 | + @echo "Build finished; now you can process the pickle files." |
69 | + |
70 | +json: |
71 | + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json |
72 | + @echo |
73 | + @echo "Build finished; now you can process the JSON files." |
74 | + |
75 | +htmlhelp: |
76 | + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp |
77 | + @echo |
78 | + @echo "Build finished; now you can run HTML Help Workshop with the" \ |
79 | + ".hhp project file in $(BUILDDIR)/htmlhelp." |
80 | + |
81 | +qthelp: |
82 | + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp |
83 | + @echo |
84 | + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ |
85 | + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" |
86 | + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Renamer.qhcp" |
87 | + @echo "To view the help file:" |
88 | + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Renamer.qhc" |
89 | + |
90 | +devhelp: |
91 | + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp |
92 | + @echo |
93 | + @echo "Build finished." |
94 | + @echo "To view the help file:" |
95 | + @echo "# mkdir -p $$HOME/.local/share/devhelp/Renamer" |
96 | + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Renamer" |
97 | + @echo "# devhelp" |
98 | + |
99 | +epub: |
100 | + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub |
101 | + @echo |
102 | + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." |
103 | + |
104 | +latex: |
105 | + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex |
106 | + @echo |
107 | + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." |
108 | + @echo "Run \`make' in that directory to run these through (pdf)latex" \ |
109 | + "(use \`make latexpdf' here to do that automatically)." |
110 | + |
111 | +latexpdf: |
112 | + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex |
113 | + @echo "Running LaTeX files through pdflatex..." |
114 | + make -C $(BUILDDIR)/latex all-pdf |
115 | + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." |
116 | + |
117 | +text: |
118 | + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text |
119 | + @echo |
120 | + @echo "Build finished. The text files are in $(BUILDDIR)/text." |
121 | + |
122 | +man: |
123 | + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man |
124 | + @echo |
125 | + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." |
126 | + |
127 | +changes: |
128 | + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes |
129 | + @echo |
130 | + @echo "The overview file is in $(BUILDDIR)/changes." |
131 | + |
132 | +linkcheck: |
133 | + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck |
134 | + @echo |
135 | + @echo "Link check complete; look for any errors in the above output " \ |
136 | + "or in $(BUILDDIR)/linkcheck/output.txt." |
137 | + |
138 | +doctest: |
139 | + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest |
140 | + @echo "Testing of doctests in the sources finished, look at the " \ |
141 | + "results in $(BUILDDIR)/doctest/output.txt." |
142 | |
143 | === added directory 'docs/code' |
144 | === added file 'docs/code/plugins_command.py' |
145 | --- docs/code/plugins_command.py 1970-01-01 00:00:00 +0000 |
146 | +++ docs/code/plugins_command.py 2010-11-01 08:51:04 +0000 |
147 | @@ -0,0 +1,42 @@ |
148 | +import os |
149 | +import string |
150 | +import time |
151 | + |
152 | +from renamer.plugin import RenamingCommand |
153 | +from renamer.errors import PluginError |
154 | + |
155 | + |
156 | +class ReadableTimestamps(RenamingCommand): |
157 | + # The name of our command, as it will be used from the command-line. |
158 | + name = 'timestamp' |
159 | + |
160 | + # A brief description of the command's purpose, displayed in --help output. |
161 | + description = 'Rename files with POSIX timestamps to human-readble times.' |
162 | + |
163 | + # Command-line parameters we support. |
164 | + optParameters = [ |
165 | + ('format', 'f', '%Y-%m-%d %H-%M-%S', 'strftime format.')] |
166 | + |
167 | + # The default name template to use if no name template is specified via the |
168 | + # command-line or configuration file. |
169 | + defaultNameTemplate = string.Template('$time') |
170 | + |
171 | + # IRenamerCommand |
172 | + |
173 | + def processArgument(self, arg): |
174 | + # The extension is not needed as it will be determined from the |
175 | + # original file name. |
176 | + name, ext = arg.splitext() |
177 | + try: |
178 | + # Try convert the filename to a floating point number. |
179 | + timestamp = float(name) |
180 | + except (TypeError, ValueError): |
181 | + # If it is not a floating point number then we raise an exception |
182 | + # to stop the process. |
183 | + raise PluginError('%r is not a valid timestamp' % (name,)) |
184 | + else: |
185 | + # Convert and format the timestamp according to the "format" |
186 | + # command-line parameter. |
187 | + t = time.localtime(timestamp) |
188 | + return { |
189 | + 'time': time.strftime(self['format'], t)} |
190 | |
191 | === added file 'docs/conf.py' |
192 | --- docs/conf.py 1970-01-01 00:00:00 +0000 |
193 | +++ docs/conf.py 2010-11-01 08:51:04 +0000 |
194 | @@ -0,0 +1,216 @@ |
195 | +# -*- coding: utf-8 -*- |
196 | +# |
197 | +# Renamer documentation build configuration file, created by |
198 | +# sphinx-quickstart on Thu Oct 21 09:53:03 2010. |
199 | +# |
200 | +# This file is execfile()d with the current directory set to its containing dir. |
201 | +# |
202 | +# Note that not all possible configuration values are present in this |
203 | +# autogenerated file. |
204 | +# |
205 | +# All configuration values have a default; values that are commented out |
206 | +# serve to show the default. |
207 | + |
208 | +import sys, os |
209 | + |
210 | +# If extensions (or modules to document with autodoc) are in another directory, |
211 | +# add these directories to sys.path here. If the directory is relative to the |
212 | +# documentation root, use os.path.abspath to make it absolute, like shown here. |
213 | +#sys.path.insert(0, os.path.abspath('.')) |
214 | + |
215 | +# -- General configuration ----------------------------------------------------- |
216 | + |
217 | +# If your documentation needs a minimal Sphinx version, state it here. |
218 | +#needs_sphinx = '1.0' |
219 | + |
220 | +# Add any Sphinx extension module names here, as strings. They can be extensions |
221 | +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. |
222 | +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage'] |
223 | + |
224 | +# Add any paths that contain templates here, relative to this directory. |
225 | +templates_path = ['templates'] |
226 | + |
227 | +# The suffix of source filenames. |
228 | +source_suffix = '.rst' |
229 | + |
230 | +# The encoding of source files. |
231 | +#source_encoding = 'utf-8-sig' |
232 | + |
233 | +# The master toctree document. |
234 | +master_doc = 'index' |
235 | + |
236 | +# General information about the project. |
237 | +project = u'Renamer' |
238 | +copyright = u'2010, Jonathan Jacobs, Tristan Seligmann, Andrew Snowden' |
239 | + |
240 | +# The version info for the project you're documenting, acts as replacement for |
241 | +# |version| and |release|, also used in various other places throughout the |
242 | +# built documents. |
243 | +# |
244 | +# The short X.Y version. |
245 | +version = '0.1.0' |
246 | +# The full version, including alpha/beta/rc tags. |
247 | +release = '0.1.0' |
248 | + |
249 | +# The language for content autogenerated by Sphinx. Refer to documentation |
250 | +# for a list of supported languages. |
251 | +#language = None |
252 | + |
253 | +# There are two options for replacing |today|: either, you set today to some |
254 | +# non-false value, then it is used: |
255 | +#today = '' |
256 | +# Else, today_fmt is used as the format for a strftime call. |
257 | +#today_fmt = '%B %d, %Y' |
258 | + |
259 | +# List of patterns, relative to source directory, that match files and |
260 | +# directories to ignore when looking for source files. |
261 | +exclude_patterns = ['_build'] |
262 | + |
263 | +# The reST default role (used for this markup: `text`) to use for all documents. |
264 | +#default_role = None |
265 | + |
266 | +# If true, '()' will be appended to :func: etc. cross-reference text. |
267 | +#add_function_parentheses = True |
268 | + |
269 | +# If true, the current module name will be prepended to all description |
270 | +# unit titles (such as .. function::). |
271 | +#add_module_names = True |
272 | + |
273 | +# If true, sectionauthor and moduleauthor directives will be shown in the |
274 | +# output. They are ignored by default. |
275 | +#show_authors = False |
276 | + |
277 | +# The name of the Pygments (syntax highlighting) style to use. |
278 | +pygments_style = 'sphinx' |
279 | + |
280 | +# A list of ignored prefixes for module index sorting. |
281 | +#modindex_common_prefix = [] |
282 | + |
283 | + |
284 | +# -- Options for HTML output --------------------------------------------------- |
285 | + |
286 | +# The theme to use for HTML and HTML Help pages. See the documentation for |
287 | +# a list of builtin themes. |
288 | +html_theme = 'default' |
289 | + |
290 | +# Theme options are theme-specific and customize the look and feel of a theme |
291 | +# further. For a list of options available for each theme, see the |
292 | +# documentation. |
293 | +#html_theme_options = {} |
294 | + |
295 | +# Add any paths that contain custom themes here, relative to this directory. |
296 | +#html_theme_path = [] |
297 | + |
298 | +# The name for this set of Sphinx documents. If None, it defaults to |
299 | +# "<project> v<release> documentation". |
300 | +#html_title = None |
301 | + |
302 | +# A shorter title for the navigation bar. Default is the same as html_title. |
303 | +#html_short_title = None |
304 | + |
305 | +# The name of an image file (relative to this directory) to place at the top |
306 | +# of the sidebar. |
307 | +#html_logo = None |
308 | + |
309 | +# The name of an image file (within the static path) to use as favicon of the |
310 | +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 |
311 | +# pixels large. |
312 | +#html_favicon = None |
313 | + |
314 | +# Add any paths that contain custom static files (such as style sheets) here, |
315 | +# relative to this directory. They are copied after the builtin static files, |
316 | +# so a file named "default.css" will overwrite the builtin "default.css". |
317 | +html_static_path = ['static'] |
318 | + |
319 | +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
320 | +# using the given strftime format. |
321 | +#html_last_updated_fmt = '%b %d, %Y' |
322 | + |
323 | +# If true, SmartyPants will be used to convert quotes and dashes to |
324 | +# typographically correct entities. |
325 | +#html_use_smartypants = True |
326 | + |
327 | +# Custom sidebar templates, maps document names to template names. |
328 | +#html_sidebars = {} |
329 | + |
330 | +# Additional templates that should be rendered to pages, maps page names to |
331 | +# template names. |
332 | +#html_additional_pages = {} |
333 | + |
334 | +# If false, no module index is generated. |
335 | +#html_domain_indices = True |
336 | + |
337 | +# If false, no index is generated. |
338 | +#html_use_index = True |
339 | + |
340 | +# If true, the index is split into individual pages for each letter. |
341 | +#html_split_index = False |
342 | + |
343 | +# If true, links to the reST sources are added to the pages. |
344 | +#html_show_sourcelink = True |
345 | + |
346 | +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. |
347 | +#html_show_sphinx = True |
348 | + |
349 | +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. |
350 | +#html_show_copyright = True |
351 | + |
352 | +# If true, an OpenSearch description file will be output, and all pages will |
353 | +# contain a <link> tag referring to it. The value of this option must be the |
354 | +# base URL from which the finished HTML is served. |
355 | +#html_use_opensearch = '' |
356 | + |
357 | +# This is the file name suffix for HTML files (e.g. ".xhtml"). |
358 | +#html_file_suffix = None |
359 | + |
360 | +# Output file base name for HTML help builder. |
361 | +htmlhelp_basename = 'Renamerdoc' |
362 | + |
363 | + |
364 | +# -- Options for LaTeX output -------------------------------------------------- |
365 | + |
366 | +# The paper size ('letter' or 'a4'). |
367 | +#latex_paper_size = 'letter' |
368 | + |
369 | +# The font size ('10pt', '11pt' or '12pt'). |
370 | +#latex_font_size = '10pt' |
371 | + |
372 | +# Grouping the document tree into LaTeX files. List of tuples |
373 | +# (source start file, target name, title, author, documentclass [howto/manual]). |
374 | +latex_documents = [ |
375 | + ('index', 'Renamer.tex', u'Renamer Documentation', |
376 | + u'Jonathan Jacobs, Tristan Seligmann, Andrew Snowden', 'manual'), |
377 | +] |
378 | + |
379 | +# The name of an image file (relative to this directory) to place at the top of |
380 | +# the title page. |
381 | +#latex_logo = None |
382 | + |
383 | +# For "manual" documents, if this is true, then toplevel headings are parts, |
384 | +# not chapters. |
385 | +#latex_use_parts = False |
386 | + |
387 | +# If true, show page references after internal links. |
388 | +#latex_show_pagerefs = False |
389 | + |
390 | +# If true, show URL addresses after external links. |
391 | +#latex_show_urls = False |
392 | + |
393 | +# Additional stuff for the LaTeX preamble. |
394 | +#latex_preamble = '' |
395 | + |
396 | +# Documents to append as an appendix to all manuals. |
397 | +#latex_appendices = [] |
398 | + |
399 | +# If false, no module index is generated. |
400 | +#latex_domain_indices = True |
401 | + |
402 | + |
403 | +# -- Options for manual page output -------------------------------------------- |
404 | + |
405 | +# One entry per manual page. List of tuples |
406 | +# (source start file, name, description, authors, manual section). |
407 | +man_pages = [ |
408 | + ('manual', 'rn', u'an extensible mass file renamer', |
409 | + [u'Jonathan Jacobs', u'Tristan Seligmann', u'Andrew Snowden'], 1) |
410 | +] |
411 | |
412 | === added file 'docs/index.rst' |
413 | --- docs/index.rst 1970-01-01 00:00:00 +0000 |
414 | +++ docs/index.rst 2010-11-01 08:51:04 +0000 |
415 | @@ -0,0 +1,16 @@ |
416 | +Renamer |version| documentation |
417 | +=============================== |
418 | + |
419 | +Contents: |
420 | + |
421 | +.. toctree:: |
422 | + :maxdepth: 3 |
423 | + |
424 | + manual |
425 | + plugins |
426 | + |
427 | +Indices and tables |
428 | +================== |
429 | + |
430 | +* :ref:`genindex` |
431 | +* :ref:`search` |
432 | |
433 | === added file 'docs/make.bat' |
434 | --- docs/make.bat 1970-01-01 00:00:00 +0000 |
435 | +++ docs/make.bat 2010-11-01 08:51:04 +0000 |
436 | @@ -0,0 +1,155 @@ |
437 | +@ECHO OFF |
438 | + |
439 | +REM Command file for Sphinx documentation |
440 | + |
441 | +if "%SPHINXBUILD%" == "" ( |
442 | + set SPHINXBUILD=sphinx-build |
443 | +) |
444 | +set BUILDDIR=_build |
445 | +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . |
446 | +if NOT "%PAPER%" == "" ( |
447 | + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% |
448 | +) |
449 | + |
450 | +if "%1" == "" goto help |
451 | + |
452 | +if "%1" == "help" ( |
453 | + :help |
454 | + echo.Please use `make ^<target^>` where ^<target^> is one of |
455 | + echo. html to make standalone HTML files |
456 | + echo. dirhtml to make HTML files named index.html in directories |
457 | + echo. singlehtml to make a single large HTML file |
458 | + echo. pickle to make pickle files |
459 | + echo. json to make JSON files |
460 | + echo. htmlhelp to make HTML files and a HTML help project |
461 | + echo. qthelp to make HTML files and a qthelp project |
462 | + echo. devhelp to make HTML files and a Devhelp project |
463 | + echo. epub to make an epub |
464 | + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter |
465 | + echo. text to make text files |
466 | + echo. man to make manual pages |
467 | + echo. changes to make an overview over all changed/added/deprecated items |
468 | + echo. linkcheck to check all external links for integrity |
469 | + echo. doctest to run all doctests embedded in the documentation if enabled |
470 | + goto end |
471 | +) |
472 | + |
473 | +if "%1" == "clean" ( |
474 | + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i |
475 | + del /q /s %BUILDDIR%\* |
476 | + goto end |
477 | +) |
478 | + |
479 | +if "%1" == "html" ( |
480 | + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html |
481 | + echo. |
482 | + echo.Build finished. The HTML pages are in %BUILDDIR%/html. |
483 | + goto end |
484 | +) |
485 | + |
486 | +if "%1" == "dirhtml" ( |
487 | + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml |
488 | + echo. |
489 | + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. |
490 | + goto end |
491 | +) |
492 | + |
493 | +if "%1" == "singlehtml" ( |
494 | + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml |
495 | + echo. |
496 | + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. |
497 | + goto end |
498 | +) |
499 | + |
500 | +if "%1" == "pickle" ( |
501 | + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle |
502 | + echo. |
503 | + echo.Build finished; now you can process the pickle files. |
504 | + goto end |
505 | +) |
506 | + |
507 | +if "%1" == "json" ( |
508 | + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json |
509 | + echo. |
510 | + echo.Build finished; now you can process the JSON files. |
511 | + goto end |
512 | +) |
513 | + |
514 | +if "%1" == "htmlhelp" ( |
515 | + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp |
516 | + echo. |
517 | + echo.Build finished; now you can run HTML Help Workshop with the ^ |
518 | +.hhp project file in %BUILDDIR%/htmlhelp. |
519 | + goto end |
520 | +) |
521 | + |
522 | +if "%1" == "qthelp" ( |
523 | + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp |
524 | + echo. |
525 | + echo.Build finished; now you can run "qcollectiongenerator" with the ^ |
526 | +.qhcp project file in %BUILDDIR%/qthelp, like this: |
527 | + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Renamer.qhcp |
528 | + echo.To view the help file: |
529 | + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Renamer.ghc |
530 | + goto end |
531 | +) |
532 | + |
533 | +if "%1" == "devhelp" ( |
534 | + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp |
535 | + echo. |
536 | + echo.Build finished. |
537 | + goto end |
538 | +) |
539 | + |
540 | +if "%1" == "epub" ( |
541 | + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub |
542 | + echo. |
543 | + echo.Build finished. The epub file is in %BUILDDIR%/epub. |
544 | + goto end |
545 | +) |
546 | + |
547 | +if "%1" == "latex" ( |
548 | + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex |
549 | + echo. |
550 | + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. |
551 | + goto end |
552 | +) |
553 | + |
554 | +if "%1" == "text" ( |
555 | + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text |
556 | + echo. |
557 | + echo.Build finished. The text files are in %BUILDDIR%/text. |
558 | + goto end |
559 | +) |
560 | + |
561 | +if "%1" == "man" ( |
562 | + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man |
563 | + echo. |
564 | + echo.Build finished. The manual pages are in %BUILDDIR%/man. |
565 | + goto end |
566 | +) |
567 | + |
568 | +if "%1" == "changes" ( |
569 | + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes |
570 | + echo. |
571 | + echo.The overview file is in %BUILDDIR%/changes. |
572 | + goto end |
573 | +) |
574 | + |
575 | +if "%1" == "linkcheck" ( |
576 | + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck |
577 | + echo. |
578 | + echo.Link check complete; look for any errors in the above output ^ |
579 | +or in %BUILDDIR%/linkcheck/output.txt. |
580 | + goto end |
581 | +) |
582 | + |
583 | +if "%1" == "doctest" ( |
584 | + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest |
585 | + echo. |
586 | + echo.Testing of doctests in the sources finished, look at the ^ |
587 | +results in %BUILDDIR%/doctest/output.txt. |
588 | + goto end |
589 | +) |
590 | + |
591 | +:end |
592 | |
593 | === added file 'docs/manual.rst' |
594 | --- docs/manual.rst 1970-01-01 00:00:00 +0000 |
595 | +++ docs/manual.rst 2010-11-01 08:51:04 +0000 |
596 | @@ -0,0 +1,247 @@ |
597 | +.. index:: manual, rn |
598 | + |
599 | +Renamer manual |
600 | +============== |
601 | + |
602 | +======== |
603 | +SYNOPSIS |
604 | +======== |
605 | + |
606 | +rn [*options*] command [*options*] argument ... |
607 | + |
608 | + |
609 | +=========== |
610 | +DESCRIPTION |
611 | +=========== |
612 | + |
613 | +**rn** is a command line interface to Renamer, an extensible utility for |
614 | +renaming files that also keeps a log of previous activities, which allows |
615 | +actions to be reversed. |
616 | + |
617 | +The required *command* argument selects which renamer command to execute. Most, |
618 | +but not all, commands invoke the renaming process on the provided arguments, |
619 | +the :ref:`undo` command is one example that differs. Consult ``--help`` for a |
620 | +list of available commands and the :ref:`COMMANDS` section for descriptions of |
621 | +the builtin commands. |
622 | + |
623 | +Renamer can be extended with new commands via Python plugins. |
624 | + |
625 | + |
626 | +======= |
627 | +OPTIONS |
628 | +======= |
629 | + |
630 | +-g, --glob |
631 | + Expand arguments as UNIX-style globs. |
632 | + |
633 | +-x, --one-file-system |
634 | + Don't cross filesystems. This is primarily useful for avoiding copy-delete |
635 | + behavior when renaming will cross file-system boundaries. |
636 | + |
637 | +-n, --no-act |
638 | + Perform a trial run with no changes made. |
639 | + |
640 | +--link-src |
641 | + Create a symlink at the source. The file will be moved to its new location |
642 | + and a symlink created at its original location. |
643 | + |
644 | +--link-dst |
645 | + Create a symlink at the destination. The original file will not be moved |
646 | + but a symlink will be created at the new location. |
647 | + |
648 | +-c file, --config=file |
649 | + Read configuration defaults from *file*. The default configuration is read |
650 | + from *~/.renamer/renamer.conf*. See the :ref:`CONFIGURATION` section for |
651 | + more information. |
652 | + |
653 | +-e template, --name=template |
654 | + Formatted filename. See the :ref:`TEMPLATES` section for more information. |
655 | + |
656 | +-p template, --prefix=template |
657 | + Formatted path to prefix to files before renaming. See the :ref:`TEMPLATES` |
658 | + section for more information. |
659 | + |
660 | +-l number, --concurrent=number |
661 | + Maximum number of asynchronous tasks to perform concurrently. The default |
662 | + is 10. |
663 | + |
664 | +--help |
665 | + Display a help message describing Renamer's command-line options. |
666 | + |
667 | +-q, --quiet |
668 | + Suppress output. |
669 | + |
670 | +--version |
671 | + Display version information. |
672 | + |
673 | +-v, --verbose |
674 | + Increase output, use more times for greater effect. |
675 | + |
676 | + |
677 | +.. index:: commands |
678 | + |
679 | +.. _commands: |
680 | + |
681 | +======== |
682 | +COMMANDS |
683 | +======== |
684 | + |
685 | +Commands are the parts of Renamer that process arguments and make things |
686 | +happen. Most commands will extract metadata from each argument in some fashion |
687 | +and store that metadata in template variables which is used to rename the |
688 | +files. |
689 | + |
690 | +.. index:: tvrage |
691 | + |
692 | +.. _tvrage: |
693 | + |
694 | +tvrage |
695 | +------ |
696 | + |
697 | +--series |
698 | + Override the series name metadata. |
699 | + |
700 | +--season |
701 | + Override the season number metadata. |
702 | + |
703 | +--episode |
704 | + Override the episode number metadata. |
705 | + |
706 | +Use TV episode metadata from filenames (such as ``Lost S01E01.avi``) to consult |
707 | +the `TV Rage`_ database for detailed and accurate metadata used in renaming. |
708 | + |
709 | +.. _TV Rage: http://tvrage.com/ |
710 | + |
711 | +Renamer is able to extract metadata from a wide variety of filename structures. |
712 | +Unfortunately, since useful metadata within the video container itself is |
713 | +extremely rare, the only reliable way to extract information is from the |
714 | +filename, meaning that filenames should be as clear as possible and contain as |
715 | +much useful metadata as possible. |
716 | + |
717 | +In the event a filename does not contain enough information to determine a |
718 | +name, season and episode number you can use the override command-line options |
719 | +``--series``, ``--season`` and ``--episode``. Specifying any one of these will |
720 | +accomplish two things: |
721 | + |
722 | +1. Override any detected metadata in the filename for that particular |
723 | + component, and; |
724 | + |
725 | +2. Relax the filename detection techniques so that less specific filenames can |
726 | + match when there is enough combined metadata between filenames and |
727 | + overrides. For example: A file named ``House - 1.avi`` combined with |
728 | + ``--season=2`` means that there is enough metadata to look up information |
729 | + for the *first* episode of the *second* season of the show "House". |
730 | + |
731 | + |
732 | +.. index:: audio |
733 | + |
734 | +.. _audio: |
735 | + |
736 | +audio |
737 | +----- |
738 | + |
739 | +Use audio metadata from files for renaming. A wide variety of audio and audio |
740 | +metadata formats are supported. |
741 | + |
742 | + |
743 | +.. index:: undo |
744 | + |
745 | +.. _undo: |
746 | + |
747 | +undo |
748 | +---- |
749 | + |
750 | +--ignore-errors |
751 | + Do not stop the process when encountering OS errors. |
752 | + |
753 | + |
754 | +Undo previous Renamer actions. |
755 | + |
756 | +The ``action`` subcommand will undo individual actions while the ``changeset`` |
757 | +subcommand will undo entire changesets, once an item has been undone it is |
758 | +removed from the history. The ``forget`` subcommand will remove an item from |
759 | +history without undoing it. |
760 | + |
761 | +Use the ``list`` subcommand to find identifiers for the changesets or actions |
762 | +to undo. |
763 | + |
764 | + |
765 | +.. index:: templates |
766 | + |
767 | +.. _templates: |
768 | + |
769 | +========= |
770 | +TEMPLATES |
771 | +========= |
772 | + |
773 | +A Python template string, as described by the Python `template documentation`_, |
774 | +can contain variables that will be substituted with runtime values from Renamer |
775 | +commands. |
776 | + |
777 | +.. _template documentation: |
778 | + http://docs.python.org/library/string.html#template-strings |
779 | + |
780 | +For example the :ref:`tvrage` command provides variables containing TV episode |
781 | +metadata; so a template such as:: |
782 | + |
783 | + $series S${padded_season}E${padded_episode} - $title |
784 | + |
785 | +Applied to episode 1 of season 1 of "Lost" (named "Pilot (1)") will result in:: |
786 | + |
787 | + Lost S01E01 - Pilot (1) |
788 | + |
789 | +The variables available will differ from command to command, consult the |
790 | +``--help`` output for the command to learn more. |
791 | + |
792 | + |
793 | +.. index:: configuration, config file |
794 | + |
795 | +.. _configuration: |
796 | + |
797 | +============= |
798 | +CONFIGURATION |
799 | +============= |
800 | + |
801 | +Configuration files follow a basic INI syntax. Sections are named after their |
802 | +command names, as listed in ``--help``, the global configuration section is |
803 | +named ``renamer``. Configuration options are derived from their long |
804 | +command-line counterparts without the ``--`` prefix. Flags can be turned on or |
805 | +off with values such as: ``true``, ``yes``, ``1``, ``false``, ``no``, ``0``. |
806 | + |
807 | +For example the command line:: |
808 | + |
809 | + rn --concurrent=5 --link-src --prefix=~/stuff somecommand --no-thing |
810 | + |
811 | +can be specified in a configuration file:: |
812 | + |
813 | + [renamer] |
814 | + concurrent=5 |
815 | + link-src=yes |
816 | + prefix=~/stuff |
817 | + |
818 | + [somecommand] |
819 | + no-thing=yes |
820 | + |
821 | +It is also possible to specify global configuration options in a command |
822 | +section to override them only for that specific command. |
823 | + |
824 | +Arguments specified on the command line will override values in the |
825 | +configuration file. |
826 | + |
827 | + |
828 | +==== |
829 | +BUGS |
830 | +==== |
831 | + |
832 | +Please report any bugs to the `Renamer Launchpad project`_ |
833 | +``<http://launchpad.net/renamer/>``. |
834 | + |
835 | +.. _Renamer Launchpad project: http://launchpad.net/renamer/ |
836 | + |
837 | + |
838 | +===== |
839 | +FILES |
840 | +===== |
841 | + |
842 | +~/.renamer/renamer.conf |
843 | + Contains the user's default configuration. |
844 | |
845 | === added file 'docs/plugins.rst' |
846 | --- docs/plugins.rst 1970-01-01 00:00:00 +0000 |
847 | +++ docs/plugins.rst 2010-11-01 08:51:04 +0000 |
848 | @@ -0,0 +1,134 @@ |
849 | +.. index:: plugins |
850 | + |
851 | +Creating a Renamer Plugin |
852 | +========================= |
853 | + |
854 | +Introduction |
855 | +------------ |
856 | + |
857 | +Renamer plugins are Python code, discovered by Twisted's `plugin |
858 | +system`_, that extends Renamer's functionality without having to modify the |
859 | +core of Renamer. |
860 | + |
861 | +.. _plugin system: |
862 | + http://twistedmatrix.com/documents/current/core/howto/plugin.html |
863 | + |
864 | +There are two kinds of pluggable code in Renamer: |
865 | + |
866 | +1. Commands that perform actions unrelated to directly renaming a file. An |
867 | + example of this would be the `undo` command. |
868 | + |
869 | +2. Renaming commands that determine new filenames from existing files and |
870 | + ultimately result in an input being renamed. An example of this would be the |
871 | + :ref:`tvrage` command. |
872 | + |
873 | +Since the topic of creating commands that are not directly related to renaming |
874 | +is so broad, this document will primarily focus on creating a command that |
875 | +performs renaming. |
876 | + |
877 | + |
878 | +Foundations |
879 | +----------- |
880 | + |
881 | +Renamer commands are simply Twisted `Options`_ subclasses with a few extra bits |
882 | +thrown in, so all the usual Options attributes (such as ``optParameters``) are |
883 | +available for use and should be how you expose additional options for your |
884 | +command. |
885 | + |
886 | +.. _Options: |
887 | + http://twistedmatrix.com/documents/current/core/howto/options.html |
888 | + |
889 | +In almost all cases you will want to inherit from the ``RenamingCommand`` base |
890 | +class, as it ensure your subclass provides all the right interfaces as well as |
891 | +invoking your command and performing the actual file renaming. |
892 | + |
893 | +At the heart of a renaming command is ``processArgument`` which accepts one |
894 | +argument and returns a Python dictionary. That dictionary is then used to |
895 | +perform `template substitution`_ on the ``name`` and ``prefix`` command-line |
896 | +options (or, if they're not given, command-specific defaults.) This process of |
897 | +calling ``processArgument`` is repeated for each argument given, letting your |
898 | +command process one argument at a time. |
899 | + |
900 | +.. _template substitution: |
901 | + http://docs.python.org/library/string.html#template-strings |
902 | + |
903 | + |
904 | +Deferreds |
905 | +--------- |
906 | + |
907 | +If your command performs a long-running task, such as fetching data from a web |
908 | +server, you can return a `Deferred`_ from ``processArgument`` that should |
909 | +ultimately return with a Python dictionary to be used in assembling the |
910 | +destination filename. |
911 | + |
912 | +.. _Deferred: |
913 | + http://twistedmatrix.com/documents/current/core/howto/deferredindepth.html |
914 | + |
915 | + |
916 | +Sample command |
917 | +-------------- |
918 | + |
919 | +Below is the complete source code of a command that renames files named as |
920 | +POSIX timestamps (e.g. ``1287758780.4690211.txt``) to a human-readable |
921 | +representation of the timestamp (e.g. ``2010-10-22 16-46-20.txt``). |
922 | + |
923 | +.. literalinclude:: code/plugins_command.py |
924 | + :linenos: |
925 | + |
926 | + |
927 | +Installing the plugin |
928 | +--------------------- |
929 | + |
930 | +Now that we've constructed our command we need to make it available to Renamer. |
931 | +This process consists of the following simple steps: |
932 | + |
933 | +1. Create a directory for your plugins such as ``MyRenamerPlugins`` wherever you |
934 | + usually put your source code, beneath this create a directory named |
935 | + ``renamer`` and beneath that a directory named ``plugins``. |
936 | + |
937 | + Your directory tree should look like:: |
938 | + |
939 | + . |
940 | + |-- MyRenamerPlugins |
941 | + | `-- renamer |
942 | + | | `-- plugins |
943 | + |
944 | +2. Add your directory (``MyRenamerPlugins`` in the previous step) to sys.path |
945 | + (typically by adding it to the PYTHONPATH environment variable.) |
946 | + |
947 | +3. Put your plugin source code file (with a ``.py`` extension) in the |
948 | + ``MyRenamerPlugins/renamer/plugins`` directory. It is important to note that |
949 | + this directory must **not** be a Python package (i.e. it must not contain |
950 | + ``__init__.py``) and will be skipped (i.e. no plugins will be loaded) if it is |
951 | + one. |
952 | + |
953 | +4. You can verify that your plugin is visible by running an interactive Python |
954 | + prompt and doing something similar to:: |
955 | + |
956 | + >>> from renamer.plugins.timestamp import ReadableTimestamps |
957 | + >>> |
958 | + |
959 | + (This obviously assumes that you used the ``ReadableTimestamps`` example and |
960 | + stored it in a file called ``timestamp.py``.) |
961 | + |
962 | + If your plugin is installed correctly there should be no errors importing |
963 | + the module. |
964 | + |
965 | + |
966 | +Using the plugin |
967 | +---------------- |
968 | + |
969 | +After your plugin has been installed correctly you can use it:: |
970 | + |
971 | + $ touch 1287758780.4690211.txt |
972 | + $ rn timestamp 1287758780.4690211.txt |
973 | + $ ls |
974 | + 2010-10-22 16-46-20.txt |
975 | + |
976 | +It is possible that you may need to regenerate the Twisted plugin cache if you |
977 | +notice nonsensical errors related to your plugin objects, especially if you're |
978 | +actively developing a plugin and testing it. Refer to the Twisted documentation |
979 | +regarding `plugin caching`_. |
980 | + |
981 | +.. _plugin caching: |
982 | + http://twistedmatrix.com/documents/current/core/howto/plugin.html#auto3 |
983 | |
984 | === removed file 'docs/rn.1' |
985 | --- docs/rn.1 2009-05-06 10:15:24 +0000 |
986 | +++ docs/rn.1 1970-01-01 00:00:00 +0000 |
987 | @@ -1,93 +0,0 @@ |
988 | -.TH RN 1 2009-05-04 "version 1.0.0" "USER COMMANDS" |
989 | - |
990 | -.SH NAME |
991 | -rn \- scriptable and extensible mass file renamer |
992 | - |
993 | -.SH SYNOPSYS |
994 | -.B rn |
995 | -.RB [\| \-g \|] |
996 | -.RB [\| \-m \|] |
997 | -.RB [\| \-R \|] |
998 | -.RB [\| \-s |
999 | -.IR file \|] |
1000 | -.RB [\| \-S |
1001 | -.IR sort \|] |
1002 | -.RB [\| \-t \|] |
1003 | -.RB [\| \-q \|] |
1004 | -.RB [\| \-v \|] |
1005 | -.RI [\| argument \|] |
1006 | -\&\.\.\. |
1007 | - |
1008 | -.SH DESCRIPTION |
1009 | -.B rn |
1010 | -is a command line interface to Renamer, a utility designed to rename files |
1011 | -according to a set of user-provided instructions, generally residing in a |
1012 | -script file. |
1013 | - |
1014 | -.SH OPTIONS |
1015 | -If no arguments are provided, |
1016 | -.B rn |
1017 | -is invoked in interactive mode. |
1018 | -.TP |
1019 | -.B \-g, \-\-glob |
1020 | -Expand arguments according to UNIX-style globs. |
1021 | -.TP |
1022 | -.B \-m, \-\-move |
1023 | -Enable \(lqmove mode\(rq, this allows scripts to perform file move operations. |
1024 | -.TP |
1025 | -.B \-R, \-\-reverse |
1026 | -Reverse the sorting order of the arguments. |
1027 | -.TP |
1028 | -.BI \-s\ file ,\ \-\-script= file |
1029 | -Execute |
1030 | -.I file\c |
1031 | -, as a script, for each argument. Each argument is invoked in its own script |
1032 | -environment, meaning that the stack is not retained between executions and |
1033 | -any stored variables are not persisted. |
1034 | -.TP |
1035 | -.BI \-S\ sort ,\ \-\-sort= sort |
1036 | -Sort arguments according to criteria: |
1037 | -.BR name , \ size , \ time . |
1038 | -.TP |
1039 | -.B \-t, \-\-dry-run |
1040 | -Perform a dry-run, meaning that no permanent operations are performed, such |
1041 | -as file renaming. |
1042 | -.TP |
1043 | -.B \-q, \-\-quiet |
1044 | -Reduce verbosity level. |
1045 | -.TP |
1046 | -.B \-v, \-\-verbose |
1047 | -Increase verbosity level. |
1048 | - |
1049 | -.SH SCRIPTING |
1050 | -Renamer operates in a stack based environment. Command line arguments, |
1051 | -function return values and function parameters are all pushed and popped |
1052 | -from the stack. |
1053 | -.PP |
1054 | -Function arguments are an exception: any arguments passed inline to a function |
1055 | -are subtracted from the total number of arguments required and appended to |
1056 | -the arguments popped from the stack. For example: |
1057 | -.PP |
1058 | -.nf |
1059 | -rn> push "foo bar baz" |
1060 | -rn> split " " |
1061 | -rn> stack |
1062 | ---> ['foo', 'bar', 'baz'] |
1063 | -.fi |
1064 | -.PP |
1065 | -Renamer's interactive mode should prove valuable in exploring the behaviour |
1066 | -of Renamer's commands, particularly the |
1067 | -.I help |
1068 | -and |
1069 | -.I commands |
1070 | -functions. |
1071 | - |
1072 | -.SH FILES |
1073 | -.TP |
1074 | -.I ~/.renamer/scripts/ |
1075 | -Directory containing user-provided scripts |
1076 | -.TP |
1077 | -.I ~/.renamer/plugin_name/config |
1078 | -Config file for configuring |
1079 | -.B plugin_name |
1080 | -individually |
1081 | |
1082 | === added directory 'docs/static' |
1083 | === added directory 'docs/templates' |
1084 | === modified file 'renamer/plugins/undo.py' |
1085 | --- renamer/plugins/undo.py 2010-10-24 17:46:32 +0000 |
1086 | +++ renamer/plugins/undo.py 2010-11-01 08:51:04 +0000 |
1087 | @@ -27,7 +27,7 @@ |
1088 | |
1089 | class _UndoMixin(object): |
1090 | optFlags = [ |
1091 | - ('ignore-errors', None, 'Do not stop the process when encountering OS errors')] |
1092 | + ('ignore-errors', None, 'Do not stop the process when encountering OS errors.')] |
1093 | |
1094 | |
1095 | def undoActions(self, options, changeset, actions): |
Conflicts between this branch and trunk have been resolved.